Key eSignature design options | Docusign

Learn about key eSignature features you should consider supporting, to maximize customer value, best practices for supporting go-live, Connect (webhooks), and installation.

Choose the Docusign plan that supports the features you need

Different Docusign plans include different product features. If your ISV application integration uses a feature that is not included in a joint customer’s current plan, they will need to upgrade their plan before they can use your integration.

You can access the current eSignature plan comparison document in the Partner Marketing Center on our partner portal. Navigate to https://partners.docusign.com/s/pmc-by-product then choose the By Product link and then the eSignature product edition comparison option under the Other section.

User settings within ISV applications Generally, your applications will be linked to a single Docusign account. The application may use a single membership for all transactions, such as sales@tully.com, or may act on behalf of individual member users of the account. For applications that are not tied to a specific single Docusign account, each user must have a configuration control that enables them to choose which of their Docusign accounts should be used by the application.

Your integration should not require more than one of its users to have System Administration privileges within Docusign.

Pro Tip: Sender View The partner application can redirect the sending user directly into the Envelope Edit screen in Docusign so the user can complete any necessary or desired edits to a draft envelope prior to sending. The partner application can then make an API call that will return a URL that enables you to embed the sender view of the Docusign UI in your application. This is a great way to allow a sender access to features in their Docusign account that might not be currently built into the partner integration.

Integration key management for ISVs

An integration key (also called a client ID) is a value that identifies each application. But, depending on your application’s architecture, each instance (each customer) of your application may need its own integration key.

SAAS multi-tenant applications only need one integration key for any number of customers. The customers must not be able to compromise the integration key’s secrets, RSA keypairs, or redirects.
SAAS multi-instance applications with a shared identity/authorization system only need one integration key for any number of customers. The customers must not see the integration key’s secrets.
SAAS pure multi-instance applications usually need one integration key per instance if the Authorization Code Grant or Implicit Grant flows are used, because each instance will typically have a different redirect URI for it. If the JWT Grant flow is used, it may be possible for all of the instances to share the integration key, because the redirect URI is only used for the consent process. Customers must not see the integration key’s secrets. Note: using a centralized service may negate the need for separate integration keys.
On-premises applications need one integration key per end customer, because the integration key’s secrets cannot be protected. Each customer will also have a different redirect URI. In many cases, depending on how your deployable instances are configured, you may need to expose the IK, the secret/keypair, and other configuration settings to the person who is installing the application.
Native mobile applications, thick client applications, and single page applications use Implicit Grant. If a common redirect URI (often with a private URL scheme) can be used for all of the application’s instances, then only one integration key is needed and it can be used for all customers. See RFC 8252 for more information on this configuration.

Use a single integration key for all of your customers

You can dramatically lower installation time and costs by using a common integration key for all your customers. Customers must not be able to access or compromise the integration key or its associated secrets.

Using a single integration key for all of your joint customers provides the highest level of customer satisfaction with the installation process. It also enables plug-and-play installations of your software.

If your application architecture doesn’t provide security for the IK’s Secret, RSA keypair, or redirect URLs, then a separate IK will be needed for each deployment. This would be the case if the application is deployed on customer premises or customer-controlled environments. In this case, each deployment will need to have its own integration key. Your company should create and manage the separate integration keys because requiring a customer to obtain their own integration key and pass the go-live developer review process can be a significant amount of work, leading to more customer service calls and less customer satisfaction with your company and its product. Depending on your partner agreement, Docusign may provide a free partner production account that can be used to manage your integration keys.

Naming integration keys

The name of your Integration Key should reflect your company and product name. This is very important, since your customers will be prompted to consent to your access. An ambiguous or otherwise unrecognized name may cause security concerns.

Designing to support go-live

If your product architecture requires that each of your customers have their own integration key (client ID), then your product should include a go-live test mode. The test mode command should implement the equivalent of 20 of your application’s transactions with Docusign. For example, your application sends a Docusign envelope using data from your application’s database and then updates your application’s user interface to show the status of the envelope. In this case, the go-live test mode would send the 20 envelopes and start the monitoring process for them. The benefit of including a go-live test mode is to enable your installation team to pass the go-live tests as quickly and as easily as possible

If an ISV partner application requires a unique Integration Key for each of their customers, each customer integration key should be created, managed and promoted to production by the partner. Each Integration Key should be created in the partner’s Docusign demo/developer account and promoted into production, through the go-live process, into the partner’s Docusign ISV partner production account so the partner can manage the integration keys and all associated configurations such as OAuth.

Note: There is a limit of 100 integration keys per Docusign account. If your integration uses unique integration keys per customer, you will need to work with the Docusign partner team as you approach the 100 integration key limit for additional partner production account provisioning.

Connect webhook settings

If your application uses the Docusign Connect webhook, we recommend that you use the per-envelope webhook eventNotification feature and include the sender’s Account ID as an envelope custom field. Your server can use the Account ID to associate the notification message with the right tenant in your application.

You can use Mutual TLS, basic authentication, OAuth for Docusign Connect, and/or HMAC security to authenticate the notification messages. ISV Partners can configure client Connect configurations to be integrator managed, enabling you to use your IK management account’s OAuth for Connect settings for each client. See Managing OAuth credentials for multiple accounts for details.

Note that your integration can programmatically create the above Connect configuration in the customer’s account. This approach minimizes the administrative work to install your application.