Docusign API integration: accounts, keys, authentication and go-live

Start with a developer account and an integration key

Create a free developer account first. Docusign calls it a free sandbox for testing an integration without touching production data. Docusign isolates this developer environment, also called the demo environment, from production, and documents you send from it carry a watermark and no legal force. In that environment API calls go to https://demo.docusign.net/restapi/v2.1/ and users sign in at account-d.docusign.com.

The demo environment may offer more than the plan you buy. A developer account can use every Docusign API that is not in beta or early access, and Docusign warns that developer accounts may have features your production plan lacks. Confirm the plan before you design around a feature.

Next, add an app. Docusign assigns the app an integration key, a GUID that identifies the integration in its authorization calls. On other pages Docusign calls the same value the client ID. Docusign recommends one integration key per integration, so that you and Docusign support can trace API activity to a single integration. An account holds up to 100 integration keys.

You add a setting to the key for each grant:

• A secret key, for the confidential form of Authorization Code Grant.
• An RSA key pair, for JWT Grant. Docusign allows a maximum of 5.
• At least one redirect URI, for every grant.

Docusign displays a secret key or an RSA key pair once, at creation, so copy it into a secrets manager at that moment. A change to a key or a redirect URI can take up to five minutes to reach the whole platform.

You create keys on the Apps and Keys page or in the Developer Console. In the console, which is in open beta, you manage keys for demo and production from one place.

Choose the authentication grant

Docusign secures API requests with OAuth 2.0. Choose the grant by one test: whether each user signs in to start a session, or a service acts for a user who is absent.

The figures come from the Docusign pages on Authorization Code Grant, JWT Grant and Implicit Grant, both the overview and the how-to.

A server-hosted integration whose users log in one by one fits the confidential grant. A single-page or native app fits the public grant, which Docusign tells you to use in place of Implicit Grant whenever possible. An integration that uses one login for all users, or manages large numbers of users, fits JWT Grant.

JWT Grant needs consent before the first call. The integration impersonates a named user, so that user or an organization administrator consents first. For the eSignature API the token request carries the scopes signature impersonation. Docusign issues no refresh token for JWT Grant and advises requesting a new access token about 15 minutes before the current one expires.

Authorization Code Grant has two time limits. The authorization code lasts two minutes. Docusign puts the refresh token at about 30 days and says the figure can change. The extended scope gives each new refresh token a full lifetime.

After any grant, call /oauth/userinfo. The response holds the account_id and base_uri that each API path needs. A user who belongs to several accounts gets one entry per account, so read base_uri from the entry whose account_id matches the account you call. In the demo environment the server-side calls run in this order:

POST https://account-d.docusign.com/oauth/token
GET  https://account-d.docusign.com/oauth/userinfo
POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes

The objects a first integration touches

The eSignature API rests on five objects: envelopes, templates, documents, recipients and tabs.

• Envelope. The container for one transaction: documents, sender, recipients and status. Set status to sent to send the envelope, or to created to save a draft.
• Template. A stored envelope definition that names roles in place of people. You create envelopes from a template. You cannot send the template itself.
• Recipient. A person who receives the envelope, with a type such as signer or carbon copy. An envelope takes up to 100 recipients.
• Tab. A place in a document where a recipient provides input. You position tabs by fixed coordinates, by anchor text or from PDF form fields.

Docusign Connect, the webhook service, sends signing events to the integration. The Docusign Connect guide covers events, security and retries. For the general choice between a push and a poll, see webhook vs API.

API limits Docusign documents

Docusign meters the account, so two integrations on one account share a budget.

The first four rows come from API resource limits, the last two from the eSignature rules and limits.

Docusign blocks calls until the start of the next hour once the account passes the hourly limit. Most responses report the budget in X-RateLimit-Remaining, and Docusign recommends that the application pause until the next hour at zero. On a plan with the limit management feature, an account administrator can raise the hourly limit in the API Usage Center, in increments of 500, up to a maximum that the plan sets. Docusign first checks the efficiency of the account's apps, and the apps need enough calls in the last seven days for that check. A limit that Docusign Support set blocks the change. The burst limit stays as it is.

Go-live: promoting the key to production

At go-live Docusign copies the integration key from the developer account to a production account. The key keeps working in the demo environment, and Docusign does not copy secrets or redirect URIs.

Docusign sets four conditions for every integration: account access to each API the app uses, compliance with the API resource limits, OAuth 2.0 authentication and the correct integration classification. For the eSignature REST API the review requires two more things: a paid production account that manages the key, and administrator access to that account. ISV partners can apply for a free management account through the partner program.

Choose the classification that fits your business model. Docusign bills envelope sends on a different model for each classification.

You request the review in the Developer Console, which is in open beta. The earlier route runs through the Apps and Keys page in eSignature Admin, and Docusign calls it the legacy process. A passed review expires if you do not promote the key within 90 days. After a decline, Docusign puts a manual review at 24 to 48 hours.

After promotion you make three changes to the application. Point authentication at account.docusign.com, read the API base URI from /oauth/userinfo, and recreate the secrets, redirect URIs and RSA keys in production. Then move users, templates and Connect configurations across.

What goes wrong in production

Calls go to the wrong host

Docusign hosts each production account on a server such as NA2 or EU, and the account's base URI names that server. Code that assumes one production host fails for accounts on another. Read base_uri from /oauth/userinfo at the user's first authentication and cache it. Docusign says accounts change base URI so seldom that a cache can last a day or more.

The JWT Grant token expires in the middle of a batch

A JWT Grant token lasts one hour, so a job that starts at minute 55 of that hour fails five minutes later. Request the next token about 15 minutes before expiry, as Docusign advises, and switch the batch to it.

The first production call returns consent_required

The error means the user has not consented, or the request lacks a required scope. Production has its own users, and none of them has consented yet. Run the consent step for the production user, or ask an organization administrator to grant consent for the domain.

The redirect URI does not match

Docusign requires an exact match, spaces and slashes included. Docusign does not copy redirect URIs at go-live, so add the production addresses by hand and compare them character by character.

Status polling fails the review

Docusign limits each app to one status request per envelope per 15 minutes, and flags a breach as a violation that can fail the go-live review. Use Connect, or poll at 20-minute intervals. After a failed review, download the log of the reviewed transactions and look for the errors.

A second integration spends the shared budget

The hourly limit covers all apps on the account. A new integration on the same account takes calls from the first one, and at the limit Docusign blocks both until the next hour. A separate key does not split the limit. Give each integration its own key, because the API Usage Center lists call volume by app and shows which one to pace. Then move status checks from polling to Connect.

When an extension app fits better

The two differ in who calls whom. In an API integration your application calls the Docusign API. In an extension app the Docusign agreement calls an external API at an extension point, such as an envelope field or a workflow step.

An extension app fits a process that runs inside Docusign: a Docusign Workflow Builder step needs a record from your CRM, or a field needs checking against your data when the signer completes it. You register the app in the Developer Console, Docusign reviews it, and you publish it on the Docusign App Center for all customers or for the accounts you name.

An API integration fits a process that your application runs. It can create and send documents and apply business logic before, during and after signing, and you choose how to distribute it.

Look for an existing app before you build either. The Docusign App Center lists apps from Docusign and its partners. Docusign publishes apps for Salesforce, HubSpot, Microsoft Dynamics 365, Workday and ServiceNow, among others. Fluidlabs publishes apps for Xero, Zoho CRM, BambooHR, Smartsheet and Wealthbox that add Read and Writeback steps to Docusign Workflow Builder. An earlier article covers what Docusign checks before it lists an app.

An AI assistant is a third kind of caller. The Docusign MCP server is in open beta and accepts tokens from the Confidential Authorization Code Grant alone.

On the platforms you connect

A Docusign integration has a second system on the other end, with its own credentials and its own rate limits.

Salesforce. For a server-to-server link, Salesforce offers the OAuth 2.0 JWT bearer flow, which signs the request with a certificate and issues no refresh token. The design matches the Docusign JWT Grant. Salesforce counts API calls per org over 24 hours: an Enterprise Edition org gets 100,000 plus 1,000 per Salesforce license, before any purchased add-ons.

HubSpot. HubSpot meters by the 10-second window and by the day. An app with private distribution gets 100 requests per 10 seconds on Free and Starter, and 190 on Professional and Enterprise. On the same page, HubSpot sets the daily allowance per account at 250,000 on Free and Starter.

NetSuite. In NetSuite, OAuth 2.0 covers REST web services and RESTlets, and SOAP web services do not support it. NetSuite meters concurrent requests. For contracts from June 2020, the base limit is 5 on the Standard service tier, 15 on Premium and 20 on Enterprise and Ultimate, plus 10 for each SuiteCloud Plus license.

Size the worker pool to the second system's limit, and pace Docusign calls under the hourly limit. Docusign allows 3,000 calls an hour by default. A NetSuite account on the Standard tier accepts five concurrent requests for the whole account, so leave slots for its other integrations.