Tips On Finding the Best Integration Model for Dropbox Sign API

Using the Dropbox Sign API, you can build an integration that translates a complex business model into simple document workflows in your site.

‍

Before development starts, you have to choose a suitable integration model that will provide you with the desired functionality and attributes you need. Integrations lacking a supported integration model are often un-optimal, difficult to maintain, or subject to breaking. The goal of this article is to give you enough information to make that choice. Jump to the Summary section to check out common sample use cases.

‍

A good way to plan an integration with the Dropbox Sign API is to understand these main aspects of the use case:

• Authentication: answers the question “Who needs a Dropbox Sign.com account?”.
• Data Ownership: answers the questions “Who owns the templates?”, “Who needs to have access to completed documents?”.
• Billing: answers the question “Who is directly paying Dropbox Sign?”.
• Requester Identity: answers the question “Who’s email address are documents sent from?”,”Whose email show up in the Audit Trail?”.
• Reporting: answers the questions “Who can see the signature requests used and left?”, “Who can see the signature requests on the API Dashboard?”, “Who can see the costs?”

In this article we’ve broken down each integration model into these 5 main aspects. You’ll see that you can use multiple models in a single integration to optimize sections of the workflow.

‍

Note: Throughout this article we will be referring to the account owner—the entity building the integration—as the “app owner”, the person using the integration will be the “user”.

‍

Before We Start

Let’s just quickly recall what we know about embedded and non-embedded workflows.

‍

In non-embedded signing, Dropbox Sign notifies the signer via email and collect their eSignature on Dropbox Sign.com. In this approach, because Dropbox Sign manages all communication, branding customization is possible but limited.

‍

‍Embedded signing on the other hand allows you to have users sign documents directly on your site in an iFrame and have full control of when/how the user is notified of events regarding their documents; making some room for advanced branding, or “white labeling”, as we call it. ‍

‍

Embedded templates gives you the ability to have users create and edit templates on your site in an iFrame for later use.

‍

For further detail about the differences between these workflows, visit this article.

‍

If you have a use case that does not work with any of these integration models, contact us! We will work with you to figure it out.

‍

This approach is probably the most common and it’s also the simplest. In this model, all documents are sent from one single Dropbox Sign account (the app owner’s account) and such account manages templates as well. In the standard integration model all embedded and non-embedded workflows are available.

‍

‍Authentication: All authentication is made with one single API key—the API key obtained from Dropbox Sign.com.

‍

‍Data ownership: All data—documents and templates—lives under the app owner’s account.‍

‍

Billing: All payments are charged to the app owner. Signature requests and templates quota are counted against the app owner’s as well.‍

‍

Requester Identity: In this model, identity verification happens when creating the account on Dropboxsign.com, and the identity of the requester is tied to the app owner’s email address. That is, the email address to show up on the Audit Trail document as the sender will match the address that’s used to login to DropboxSign.com.‍

‍

Reporting: Logging in to Dropbox Sign.com and consulting the API Dashboard, the app owner will see data for all the signature requests sent by them and related callback events, as well as API calls authenticated with their API key.

‍

If there’s any need to add attributes to templates or documents—such as custom user or document identifiers—in this model the use of the “metadata” parameter is encouraged. For example, say you have a number of collaborators who send documents for signature from your site and at some point you’ll want to know who sent which document. With the metadata tag you could set an “employee_id” attribute to the signature request on creation (maybe matching the ID of the user in session in the site) and use it for queries later.

‍

If you combine this with keeping records of your signature requests or templates in your own database, you’ll have a killer implementation where you have full control of that data.

‍

The main thing to highlight when getting in OAuth territory is that in these models the app owner and the user are both expected to have separate Dropbox Sign accounts.

‍

Remember we refer to the entity building the integration as the “app owner”, and to the person using the integration as the “user”. OAuth uses authorization tokens to prove the DropboxSign user’s identity so that the app owner can send signature requests or create templates on behalf of them.

‍

This model can be used in conjunction with embedded requesting, embedded signing, non-embedded signing, and embedded templates. Once getting an access token, you can make API calls to these workflow’s endpoints on behalf of other users, making sure to pass the access token in the format specified in our OAuth Walkthrough.

‍

“User Pays” is one of the two OAuth-based integration models we offer and also the most robust. What makes it different from “Model 3: OAuth - App Owner Pays”, you ask? Well, it’s some functionality but mainly billing: in this model it’s the user that pays Dropbox Sign directly for all signature requests and templates created on their behalf.‍

‍

Authentication:  Authentication is delegated. You’ll have the user approve your application and then generate an access token that will allow you to interact with the Dropbox Sign API on their behalf.

‍

It is common to want to go around implementing OAuth by having the user enter their credentials (or API key) in the site but this not a supported use case given the security risks involved.‍

‍

Data ownership: Completed documents and embedded templates live in the user’s account, so that the user can login to Dropbox Sign.com and view the documents they sent, even when sent or created through the app owner’s integration.

‍

Depending on the scope configured for the app, upon app authorization the app owner may have read access to user’s data such as email address and name, and management access to team settings, signature requests, API apps and templates.

‍

Note: the app owner will only be able to see users' signature requests that were created using their API app. This means that if the user receives or sends a signature request themselves, the app owner’s API calls using the access token won't be able to see them.‍

‍

Billing:  All billing goes through Dropbox Sign, charging the user for the requests sent and templates created on their behalf.

‍

‍API rate limits and quotas apply directly to the user. ‍

‍

Requester Identity: The identity of the requester is tied to the email address of the user that authorized the application.‍

‍

Reporting: Given data ownership, the user will be able to see the following on their API Dashboard:

• Analytics and Usage - Data for signature requests made by the user as well as signature requests that the app owner made on behalf of the user.
• Signature Requests - Data for signature requests made by the user as well as signature requests that the app owner made on behalf of the user.
• API Requests - Data for signature requests made by the user as well as signature requests that the app owner made on behalf of the user.
  

‍

And the app owner will see the following:

• Analytics and Usage - Data for their own API quota, but nothing related to OAuth since the user is being charged in this case.
• Signature Requests - Data only for requests that the app owner personally sent.
• App Callbacks - Data for all signature requests made on the specific app that pertains to the app owner, including signature requests made on behalf of users.
• Account Callbacks - Data only for any requests the app owner made outside of OAuth.
• API Requests - Data only for requests that the app owner made without impersonating any user.

‍

And we move on to the second OAuth-based model, where the app owner pays Dropbox Sign directly for all signature requests sent on behalf of users.

‍

I mentioned before that “App Owner Pays” is different from “User pays” not only because of billing, but also functionality. It can only be used in conjunction with embedded requesting (signature requests must be for non-embedded signing only). Embedded signing and embedded templates are not available in this model at the moment.

‍

‍Authentication:  Just as in the “User Pays” model, authentication is delegated. You’ll have the user approve your application and then generate an access token that allows you to interact with the Dropbox Sign API on their behalf.

Data ownership: Documents and templates live in the user’s account, so that the user can login to DropboxSign.com and view the documents they sent, even when sent through the app owner’s integration.

Depending on the scope configured for the app, the app owner may have access to the user’s signature requests and basic account information, such as email address and name. Nothing more.

Note: here too, the app owner will only be able to see users' signature requests that were created using their API app. This means that if the user receives or sends a signature request themselves, the app owner’s API calls using the access token won't be able to see them.

Billing:  All billing goes through Dropbox Sign, charging the app owner for all the requests made on behalf of users.

API rate limits and quotas apply directly to the app owner.

Identity: The identity of the requester is tied to the email address of the user that authorized the application.

Reporting: Given data ownership, the user will be able to see the following information on their API Dashboard:

• Analytics and Usage - Data for signature requests sent by the user, but nothing related to OAuth since the App Owner is being charged in this case.
• Signature Requests - Data for signature requests sent by the user as well as signature requests that the app owner sent on behalf of the user.
• App Callbacks - No data related to OAuth but will see callbacks for any requests the user made outside of OAuth.
• Account Callbacks - No data related to OAuth but will see callbacks for any requests the user made outside of OAuth.
• API Requests - Data for all requests made on the specific app that the app owner owns, as well as requests the user made outside of OAuth.
  

‍

And the app owner will see the following:

• Analytics and Usage - Data for all signature requests made on all apps that belong to the app owner, including signature requests made on behalf of users.
• Signature Requests - Data only for requests that the app owner personally sent. No data related to OAuth.
• App Callbacks - Data for all signature requests made on the specific app that the app owner owns, including signature requests made on behalf of users.
• Account Callbacks - Data only for any requests the App Owner made outside of OAuth.
• API Requests - Data only for requests that the app owner made without impersonating any user.

‍

Take a minute to wipe model 2 and 3 off your mind, we don’t need you thinking about having separate Dropbox Sign accounts anymore.

Embedded requesting allows the app owner to have users prepare and send signature requests directly from their site within an iFrame, but get this: documents can be sent for signature using the user’s identity. Remember how in The Standard all documents were sent using the app owner’s email address as identity? Well, what makes embedded requesting special is the ability to override the sender email so that the signature request is sent from a different email address—see the “Requester Identity” section.

Another feature of this model is that, using the proper parameters, the app owner could allow users to prepare and sign a document themselves in the same session.

Embedded requesting can be used in conjunction with non-embedded and embedded signing, as well as with The Standard and OAuth models.

Authentication:  All authentication is made with the app owner’s API key, or access token when being used in combination with OAuth.

Data ownership: Documents live under the requester’s account, being the “requester” the email address used to override the app owner’s.

Billing: All payments are charged to the app owner.

Requester Identity: The identity of the requester is defined with the API parameter "requester_email_address" when creating the document draft.

For example, Joe signs up for a Dropbox Sign account with his email “joe@example.com” and develops an integration that uses the embedded requesting workflow in his site. He then has Jane sign up to his site and verify her “jane@example.com” email address. Now Jane can send signature requests from Joe’s integration, and Joe will use “jane@example.com” as the requester_email_address so all the documents Jane sends are under her name, even though the authentication is made with Joe’s API key.

It is important to understand that Dropbox Sign delegates the email verification component, the app owner is responsible of verifying the user’s identity. Joe is responsible of making sure Jane is Jane.

Reporting: Logging in to Dropbox Sign.com and consulting the API Dashboard, the app owner will see data for all the signature requests sent by them and related callback events, as well as API calls authenticated with their API key.

Many business models naturally find suitable to organize users in teams. As you may have guessed by now, this integration model is built around a team structure, where you have several Dropbox Sign accounts sharing one single subscription.

Because of the nature of the team structure, this model is commonly used in implementations where the business model can be translated into a department organization where each department sends different types of documents to different types of users, as it allows you to keep documents and templates separated from team to team—you don’t usually need your sales and legal teams to use the same templates, right?

Another very important piece of functionality in this model is the ability to send signature requests on behalf of any team member. This is, the app owner is able to switch between team member’s API keys so that a document is sent from such team member’s email address.

This integration model is recommended for cases where the users sending documents for signature are internal to the app owner’s organization. Using it to handle external users, such as the app owner’s customers, is highly discouraged and not supported. The reason for this is potential privacy risks—for example, team admins have access to all documents and templates so a user role misconfiguration could result in external customers seeing each others data.

Although it’s mostly used for non-embedded signing, all embedded and non-embedded workflows are available in this model.

Authentication: Authentication is made with an API key.

Data ownership: All documents and templates live under the account that owns the team. However, data access depends on each team member’s role. This article describes the different team roles, and their access scope.

Billing:  All team members share a subscription. Payments are charged to the user in the team that has billing details set up. Signature requests and templates quota are decremented from the account that has billing setup as well.

Requester Identity: The identity of the requester is always tied to the email address associated with the API key that’s in use, regardless of the email associated with the account that owns the team. This means that the API key to use when creating each signature request will depend on the email address the app owner’s wants the documents to be sent from. If the document should be sent from “legal@example.com”, then the API key grabbed from the “legal@example.com” account will be the one to use.

Reporting: Logging in to Dropbox Sign.com and consulting the API Dashboard, the app owner will see data for all the signature requests sent by all team members, as well as API calls authenticated with any team member’s API key.

Similarly to The Standard, if there’s any need to add attributes to templates or documents, in this model the use of the “metadata” parameter is encouraged as well.

‍

Also well described as “multiple levels of users”. This model is not an integration model on its own but it’s used in conjunction with other Integration models, often with Model 1 or 4, to expand the solution’s functionality. It’s useful when the app owner requires to deploy their solution on different environments. Translated into Dropbox Sign terms each environment will be an API app and because API apps are identified with client_ids, each client_id will identify an environment.

A few examples of situations where an implementation may need different environments are:

• The app owner will deploy their e-signature workflows in different websites. For example, many schools may benefit from the app owner’s awesome student-sign-up workflow, and each school has a separate domain.
• The app owner needs to customize the UI for each deployment. App-level customizations like white labeling may be done to present each school a workflow that’s branded with their own logo (fancy, huh?).
• The app owner needs to set up different callback URLs for each deployment. This is usually resolved by using one single callback handler and routing the event as needed, but there could also be cases this doesn’t resolve.

‍

Can be used with all other models except for the OAuth-based.

Authentication: All authentication is made with the app owner’s API key as obtained from DropboxSign.com.

Data Ownership: All data—documents and templates—lives under the app owner’s account.

To separate out environment data, it is encouraged to use the “metadata” parameter additional to the client_id as the environment identifier, and a database. You could have a solution where you query your database to present a school with the templates available for them to use.

Billing: All payments are charged to the app owner. Signature requests and templates quota are counted against the app owner’s as well.

Requester Identity: Identity verification happens when creating the account in DropboxSign.com, and the identity of the requester is tied to the app owner’s email address.

Reporting: Logging in to DropboxSign.com and consulting the API Dashboard, the app owner will see data for all the signature requests sent by them and related callback events, as well as API calls authenticated with their API key.

A database as mentioned in “Data Ownership” may come handy to handle data for reporting as well.

‍

This model is not an integration model on its own either it’s also helpful to expand the solution’s functionality.

Say the app owner wants for their users to be able to complete an embedded requesting workflow on one site, but then have the embedded signing portion finished in another site (with a different domain). This would normally not be possible because each API app is configured with one single domain for domain verification, meaning it’s only allowed to be used on pages from this domain and its subdomains.

However, the “multi-domain API apps” functionality gives us the ability to configure API apps with two domains.

This feature that can be used with the other models (except OAuth), and with all embedded workflows. For that reason the way authentication, data ownership, billing, etc, works will be that of the integration model it’s used in conjunction with.

‍

Summary

There are several implementation options to the Dropbox Sign API - which is best for you will depend on the nature of your application.

More than a science, figuring out an integration models is an art. One of them may be just what you need. And if it’s not, the solution could be a mix of two. Here are a few sample use cases and their respective integration models:

‍