For integration developers, the path to seamless application connectivity often begins and ends with robust authentication. Failure to master API authentication can lead to security vulnerabilities, frustrating user experiences, and countless hours spent troubleshooting unforeseen errors. This document serves as your essential guide to navigating the complexities of Docusign API authentication, providing a comprehensive framework to ensure your integrations are both secure and reliable.

This guide will delve into the core concepts that underpin the Docusign authentication framework, detailing the purpose and management of tokens, the significance of scopes for defining application capabilities and obtaining user consent, and the various server roles—both Docusign servers (authorization, token, and API servers) and your application’s servers (callback server and webhook listener). I will then explain the different OAuth flavors supported by Docusign, including the recommended Authorization Code Grant flow with PKCE for secure user-present authentication, and the considerations for using JWT Grant when a user is not present. Finally, this resource provides critical insights into error handling and best practices, equipping you with the knowledge to diagnose and resolve common issues that arise during both authentication attempts and subsequent API service calls. Prepare to elevate your Docusign integration strategy by laying a solid foundation in authentication.

Core concepts refresher

Jargon and specific keywords litter API authentication discussions. To make sure that we speak the same language, I’ll define some core concepts and keywords:

• Tokens

• Scopes

• OAuth roles

• Server roles

Tokens

What is a token? In the most basic terms, a token is a unique alphanumeric string value used for authorization purposes. The OAuth 2.0 protocol, which Docusign uses to control access to all its API services, uses tokens to enable users to grant permission for apps to access resources from HTTP services without the need to share their own authentication credentials. 

Purpose

An integration client—your application, for instance—that integrates to Docusign must present an OAuth token to Docusign with every API call. The token your app presents is called an access token. An access token proves to Docusign that your client has successfully authenticated as a particular Docusign user. Another type of token, called a refresh token, is used to obtain a new access token when the original access token is close to expiring. Docusign constructs each token it issues as a JSON Web Token (JWT), as described in RFC 7519. Briefly, a JWT is a tiny database with an optional cryptographic signature that ensures authenticity. Docusign cryptographically signs access and refresh tokens as a way to detect fraudulent tokens. Docusign access tokens contain enough information for the API server to perform its function, such as proof that the token is valid and which user the token represents.

Obtaining tokens

Before your application can present an access token, it must obtain it. The entirety of OAuth revolves around obtaining and refreshing access tokens. The rest of this blog post details the various approaches for obtaining an access token. 

Duration

Every token has a defined lifetime; every token expires. The access token expires either one hour or eight hours after being issued, depending on the OAuth flow used to obtain the access token. In most cases, obtaining an access token also produces a refresh token. The refresh token lives much longer: by default, 30 days before expiring. Typically, the refresh token expires 30 days from the time that the initial access token was issued. With the extended scope, new refresh tokens expire 30 days after each refresh, enabling your application to refresh effectively forever. More information on using refresh tokens is our blog Authorization Code Grant refresh tokens.

Testing access token validity

Your application will obtain the initial access token. After some time, the access token will expire. Generally, your application will send the refresh token to obtain another access token and refresh token, continuing until the refresh token expires. Since tokens become invalid both due to expiring and being revoked, your application should be prepared to obtain a new access token even if the current time is prior to the access token expiration date. There are four main approaches for determining if the current access token is valid.

1. Always obtain a new token

2. Fix on failure

3. Pre-test via API call

4. Monitor expiration

Always obtain a new token

By far, the simplest approach is for your application to assume that no valid access token exists for each set of API calls. Before a set of API calls, your application generates a new access token and then applies it for the API calls needed. Suppose that your application will make four API calls to create an envelope, adjust the recipients, update tab values, and then send the envelope. In this case, your app would simply generate a new access token and then make the four calls, discarding the access token at the end. 

This approach has two main disadvantages. First, if the user is required to authenticate when each access token is issued, this approach means that the user must authenticate almost continuously as your application proceeds. Of course, users will quickly tire of this approach. The second disadvantage is that this approach makes needless calls to the Docusign authentication framework, putting excess load on Docusign servers. Since authentication requires a fraction of a second to complete, this approach adds latency to the user experience.

Fix on failure

The most common approach to handling invalid tokens is to fix on failure. Every API call in the application contains an exception handler for invalid tokens. When the application presents an invalid access token, Docusign returns an error that the application uses to invoke authentication code. Upon successful authentication, the application retries the failed API call. 

This approach also has disadvantages. First, this requires more complex code. The code must be able to self-recover when Docusign returns an invalid token error. Second, the application must contain a data store to manage all of the access tokens in use.

Pre-test via API call

The third approach to testing the access token validity is by performing a lightweight API call to confirm that the access token is still valid. If the lightweight call succeeds, then the access token was valid for that call and is likely valid for the next API call.

This approach has two disadvantages. First, this approach adds an additional API call per operation, adding load to the network, your application, and Docusign servers. The second disadvantage is that this approach does not fully ensure that the access token is valid for subsequent API calls. Eventually, your application will succeed on the pre-test call and the access token will expire immediately after that call succeeds, causing subsequent calls to fail. The solution to this race condition is to apply the Fix on Failure approach above when the pre-test call succeeds and subsequent calls fail. Of course, if you are going to implement the complexity of Fix on Failure anyway, then performing a pre-test call adds no real value.

Monitor expiration

The final approach to testing access token validity is to track the expiration of the token, making sure to verify that the token has not expired before using it, as described in the blog post Common API Tasks🐈: Check if your access token has expired.

The disadvantage to this approach is that your application could interpret the access token as being valid even though it is no longer valid. Clock synchronization issues could cause your clock and the Docusign clock to differ. You can hedge against this issue by refreshing tokens with sufficient time to spare, such as within 30 minutes of expiration. Finally, if for any reason an access token becomes invalid prior to expiration, this approach will continue to attempt to use the access token until it is refreshed. The solution to an invalid yet unexpired access token is to apply the Fix on Failure approach described above.

Scopes

Scopes refer to capabilities that your application intends to use on the user’s behalf. The application must specify the scopes it intends to use and the user must consent to your application using those scopes. The Authentication scopes page on the Docusign Developer Center lists all Docusign scopes.

Declaring scopes for use

Every authentication flow includes several parameters. One of those parameters is a space-delimited list of scopes. Supply the list of the minimum scopes necessary for your application to function.

Obtaining consent

Before authenticating with a set of scopes, the user must consent to your application operating on the user’s behalf with those scopes. The only way to obtain user consent is to authenticate the user via the Authorization Code Grant flow described below.

Grants

Grant is an OAuth term that describes how a user has granted access to the user’s resources. Put another way, it is the way that a user has authenticated to Docusign. Note that a Consent Grant described in the previous section is different from the grant described in this section. The grant_type parameter is passed as part of the authentication process, determining which OAuth flow is intended, as I'll describe later.

OAuth roles

In the OAuth 2.0 protocol, the actors who deal with all the tokens, scopes, and grants in the authentication process are delineated into different roles: 

• Resource owner: This is the entity that owns the resources that your app needs to access; in the case of Docusign integrations, this is your app’s user, who will grant your app access to Docusign APIs via the permissions associated with their Docusign account. 

• Client: This is the entity requesting access to resources owned by the resource owner; in the case of Docusign integrations, this is your app itself. When your app initiates the authentication process, it submits a request to the authorization server that specifies the resource owner (user) in whose stead it’s requesting access, and a list of the scopes it wishes to use on that user’s behalf. 

• Authorization server: This server orchestrates the authentication process: 

  • It provides the resource owner (your user) with an interface to supply their credentials and grant the client (your app) access to the resources and scopes requested.

  • It provides the client an authorization code that the client then uses to request an access token, which is needed for requesting information from the resource server.

  • It validates the authentication code provided by the client and issues an access token for presentation to the resource server.

  • It redirects the resource owner to an HTTPS destination specified by the client in the redirect URI, which the client provides with the authorization code when it requests an access token.

• Resource server: This server hosts the resources the client wants to access. It receives requests from the client, accompanied by the access token granted by the authorization server; validates the access token; and responds to the request accordingly.

Server roles

A Docusign integration involves up to four servers: two at Docusign and two that your application hosts. 

Docusign servers

Docusign hosts two servers for your integration: the authorization server and the resource server, also known as the API server.

Authorization server

As described in the OAuth documentation RFC 6749, your application will place a call to this server at the beginning of attempts to authenticate using the Authorization Code Grant flows. This server provides your user the opportunity to authenticate, and then determines whether or not the user has authenticated and granted your application permission to interact with Docusign on the user’s behalf. If authentication is successful, this server responds with an authorization code that your app can use to request a token. Docusign uses these demo and production endpoints for requesting authorization:.

Demo: https://account-d.docusign.com/oauth/auth

Production: https://account.docusign.com/oauth/auth

Once your app has received an authorization code, it presents that code back to the authorization server, which issues access tokens and refresh tokens that can later be used to access Docusign resources. A valid access token represents an authenticated user, not a Docusign account. Docusign uses these demo and production endpoints for requesting access tokens:

Demo: https://account-d.docusign.com/oauth/token

Production: https://account.docusign.com/oauth/token

API (Resource) server

This is the server that actually responds to your app’s resource requests. Everything else has led up to calling the API server. With a valid access token, you make calls to the API server. Docusign hosts a number of APIs, each with their own base URI, to which you add the specific path to the endpoint you wish to call. Most API server endpoints have the Docusign account ID as part of the path. Our Docusign API endpoint base paths page lists them all.

Getting the right production base path for your user

Docusign hosts API servers across the globe in multiple data centers. For our eSignature REST API and several others, the region of the world in which your user’s account is hosted determines the base URI you need to use to access Docusign APIs using their authorization. So how does your app discover which base URI to use? We host an additional endpoint on our authorization server, not part of the OAuth process, that provides this information: the user info endpoint.  Before making your first API call, identify the correct base URI for the account ID you intend to interact with by calling the user info endpoint immediately after obtaining a valid access token. The user info endpoint will return an array of Docusign accounts where the user is a member, containing the appropriate base path for each. Use that base path to construct the URL needed to call the API endpoint you wish to use. Docusign uses these Demo and Production endpoints for user info.

Demo: https://account-d.docusign.com/oauth/userinfo

Production: https://account.docusign.com/oauth/userinfo

Your servers

In addition to the Docusign servers listed above, you will deploy a callback server and a webhook listener when interacting with Docusign API endpoints.

Callback server

The callback server is necessary for many forms of authentication. This is the server that hosts the location, specified by the redirect URI, where the authorization server will redirect the user after authentication is complete.

Webhook listener

So that your application can monitor the status of Docusign envelopes, host a webhook listener. When you configure webhook events, supply this server to the webhook parameters. Docusign will send regular updates and data based on the events and data that you specify to this endpoint.

With the authentication background and server roles in place, it’s time to talk about the OAuth flavors that Docusign supports.

Docusign OAuth types

Docusign supports several flavors of OAuth (described in the OAuth documentation as flows) so that you can select the one that fits your needs. Select the choice below that best serves your customers. You may even use multiple flavors in your application to fit specific use cases.

• Authorization Code Grant with PKCE

• Authorization Code Grant without PKCE

• Implicit Grant

• JWT Grant

Let’s look at each of the flavors, including when to use, when not to use, and a typical flow. To learn more about the rationale for different flavors, read RFC 6819.

Authorization Code Grant with PKCE

This OAuth flavor provides a high level of security for authenticating a user present at the keyboard and mouse. PKCE adds a layer of validation to ensure that the client beginning the authorization process is the same client that requests the access token. This flavor should be the first choice whenever the user is present and able to authenticate.

Typical flow

When to use

• The user is present at the keyboard and mouse, available to authenticate.

• The user’s device may be vulnerable to compromise by malware, or the device is shared among multiple users; for instance, a public device.

• Your application is able to host a page at the Redirect URI.

• Your application is able to hash a code verifier value and then securely store the unhashed value between calls to the authorization server.

When not to use

• Your application needs to authenticate when the user is unavailable.

• User authentication imposes a high level of user experience friction.

For a walkthrough, see this video:

Authorization Code Grant without PKCE

As a legacy OAuth flavor, this is one of the most widely used for authenticating a user present at the keyboard and mouse. This flavor is vulnerable to an attack wherein a malicious process intercepts the authorization code and then exchanges it for an access token. If at all possible, avoid this flavor and use the Authorization Code Grant with PKCE.

Typical flow

When to use

• The user is present at the keyboard and mouse, available to authenticate.

• Your application is able to host a page at the redirect URI.

• Your application is hosted in a secure environment and can safely store secret information.

• Your application is unable to hash a code verifier value and then securely store the unhashed value between calls to the authorization server and the token server.

When not to use

• The user’s device may be vulnerable to compromise by malware, or the device is shared among multiple users; for instance, a public device.

• Your application needs to authenticate when the user is unavailable.

• User authentication imposes a high level of user experience friction.

• You have the option of using PKCE, described in the previous section.

Implicit Grant

This OAuth flavor provides the least security, but is necessary when your application cannot securely store secret information or your application is unable to host a page at the redirect URI.

When to use

• The user is present at the keyboard and mouse, available to authenticate.

• Your application is unable to host a page at the redirect URI.

• Your application cannot safely store secret information; common cases include a single-page web application (SPA), mobile application, progressive web app (PWA), or a distributed package.

When not to use

• Every chance possible!

This flavor is the least secure and should be considered as the last resort option, chosen only when no other flavor is feasible. Use this with the understanding that this flavor is the most easily compromised by attackers.

JWT Grant

This OAuth flavor provides a high level of security for authenticating without the user present. Consistent with the adage, “Security is inversely proportional to convenience,” the JWT Grant is incredibly secure and incredibly inconvenient to develop the first time.

Typical flow

When to use

• The user is not present at the keyboard and mouse, and is unavailable to authenticate.

• Your application is able to host a page at the redirect URI.

• Your application is hosted in a secure environment and can safely store secret information.

• Your application has access to crypto libraries that can cryptographically sign a JWT.

• Your application is able to authenticate the user one time via Authorization Code Grant above in order to obtain consent.

When not to use

• The user is present at the keyboard and mouse, and authentication does not unduly disrupt the user experience.

For a walkthrough, see this video:

Caution: Because the JWT Grant allows you to set an arbitrary expiration date of the JWT, you might be tempted to create a long-life JWT and then just reuse it when your application needs an access token. Understand that if a valid JWT is leaked, the holder of that JWT can exchange it for an access token at any time until the RSA public key is removed from the integration key at Docusign. Best practice is to create a JWT that is valid only long enough to obtain an access token. Giving a JWT a 60-second lifetime should be sufficient for almost all scenarios.

Now that you know about the inner workings of Docusign authentication, get started with our guides on how to choose and implement each of the different flavors.

Error handling and best practices: Common OAuth errors when integrating with Docusign and how to troubleshoot them

Suppose that you are configuring Docusign authentication and run into an issue. Perhaps you have an existing configuration, but things are no longer working. If so, you have come to the right place. This section covers different types of errors, their causes, and their resolutions. Errors take place either during authentication or when making service calls to the API server.

Authentication errors

Authentication errors happen in the process of obtaining the access token. These errors generally fall into five categories.

1. User problems

2. Integration key (IK) problems

3. Token exchange problems

4. JWT problems

5. Authentication endpoint problems

User problems

We all live in the real world where mistakes happen. Users live in the real world with us, also making mistakes. The most common issue is when a user fails to authenticate correctly to Docusign, often through attempting to use an incorrect password. Similarly, the user can decline to grant consent or even revoke consent to your application. When the user fails to authenticate to Docusign, your application will be unable to authenticate. Finally, the user must consent to all of the scopes that your application supplies during authentication. If the user has revoked consent or does not grant consent to one or more of the scopes that you supply, the authentication attempt will fail. Docusign will return an error that indicates which of these problems caused authentication to fail. The solution to all user problems is to try again to authenticate.

Integration key problems

Your application authenticates using several attributes of your integration key (IK), also known as an App in the Apps and Keys area of Docusign eSignature. The call to authenticate must include a valid IK. Any secret information that your application supplies, such as a redirect URI or secret key, must also match the IK settings in Docusign. 

Token exchange problems

Once the user authenticates, many OAuth flavors require your application to obtain an access token. While rare, problems can surface when attempting to obtain an access token. First, the authorization code must match that issued by Docusign and must be redeemed promptly. If a malicious application intercepts and then redeems the authorization code before your application redeems it, then the authentication will fail.

When using PKCE (which is always a good idea), your application must generate a code verifier and a code challenge. Your application will hash the code verifier to generate the code challenge, supplying the code challenge during the initial authentication request and then supplying the code verifier when requesting an access token. Docusign will generate its own code challenge from the code verifier that your application supplies. If Docusign’s code challenge does not match your application’s code challenge, the authentication will fail.

JWT problems

Docusign’s JWT Grant does not require the user to authenticate, but it does have many places where things can go wrong. The earliest error most developers make is either generating a malformed JWT or supplying incorrect information in the JWT itself. Another common error involves incorrectly signing the JWT with the RSA private key, or signing with the wrong RSA key. All of these will cause the authentication to fail. A terrific online tool for validating JWT structure and signature is the JWT Debugger.

Authentication endpoint problems

Several issues can arise when constructing an endpoint path. A common error is hardcoding the endpoint for the demo environment, which will cause failures when attempting to authenticate in the production environment. Path assembly can also introduce malformed paths: test each complete path separately from your application.

Service call errors

Even after your successful authentication, your application can experience errors when attempting to make service calls to the API server. These generally fall into four categories.

1. Access token problems

2. User membership problems

3. Wrong endpoints

4. Invalid IK / account ID combination for ISV 2.1 accounts

Access token problems

When your application presents an invalid or expired access token, the service call will fail. The solution is to obtain another access token, either through the same process used to obtain the current access token or through the use of a refresh token.

User membership problems

Making an API service call requires presenting a valid access token and supplying the Docusign account ID as part of the path. The access token implies a Docusign user ID. If that user ID lacks a membership on the account associated with the account ID, the API call will fail. If the user has a membership with the target Docusign account, but lacks the appropriate permissions to execute the operation requested, the call will fail. For example, if a user is defined for an account, but that user lacks permissions to send envelopes, then an API call to create an envelope using an access token for that user will fail.

Keep in mind that Docusign users are in one internal table and Docusign accounts are in another. A third, and hidden, internal Docusign table serves as a bridge table to associate users to accounts, known as memberships. A user can exist but not be associated with a particular account.

Wrong endpoints

A common mistake involves calling the wrong API endpoints. Often this arises because the integration does not call using the correct base URI for the account. As noted above, make sure that the integration calls the user info endpoint immediately upon successful authentication to learn the correct base URI for that user. Use that base URI for the remainder of the session associated with the access token.

Sometimes path construction leads to an invalid path for the API call. If you encounter errors, log the path the application is calling and attempt to call it externally, such as through Postman.

Invalid IK/AccountID combination for ISV 2.1 Accounts

As a rule, within an environment, any user can authenticate using any IK and any IK can interact with any account. That means that any demo user worldwide can authenticate using any demo IK worldwide, and the resulting access token can interact with any demo account worldwide. The same is true for production. Recently, an exception to this rule has emerged.

In 2024, Docusign introduced ISV 2.1 accounts to solve for the specific needs of ISVs. One of the design goals of ISV 2.1 was to prevent unauthorized service charges to Docusign accounts operated by ISVs. A historical attack vector for incurring unauthorized charges was for an external application to make API calls to Docusign accounts operated by ISVs. To eliminate this risk, ISV 2.1 accounts only allow specific IKs to make API calls to them. If an API call is made using an access token associated with an IK not specifically authorized, the API call will fail.

The authorized list of IKs for a particular set of accounts is the IKs homed at the default Organization account. Every IK has a home account, and generally, the IK home account is mostly inconsequential. The home account in demo is the account wherein the IK was created. The home account in production is the account to which the IK was promoted. Every organization has a default Docusign account. When an API call is made to an ISV 2.1 account, Docusign first validates that the IK used to authenticate is homed on the default account of the Organization to which the account of the API call belongs. If the IK is not homed on the Organization default account, the API call will fail.

This section described the most frequent sources of authentication failure at Docusign and their causes. As soon as you encounter an API error, come back here to troubleshoot the cause and take corrective action.

Recap and next steps for building robust Docusign integrations

Mastering API authentication for Docusign integrations involves understanding core concepts such as tokens: their purpose, duration, and various validity testing approaches, including "Fix on Failure" as the most common strategy. It also requires comprehending the significance of scopes for defining application capabilities and obtaining user consent. Furthermore, make sure to understand the server roles within the Docusign ecosystem (authorization and API servers) and your own application (callback server and webhook listener), particularly obtaining the correct base URI for API calls immediately after authentication.

Choose the appropriate OAuth flavor for security and functionality:

• Authorization Code Grant with PKCE is highly recommended as the first choice when a user is present and able to authenticate, due to its enhanced security. 

• For scenarios without a user present, JWT Grant provides high security, though developers must carefully manage JWT lifetimes to minimize risk.

Building resilient Docusign integrations hinges on proactive error handling and troubleshooting. This includes anticipating and addressing both authentication failures—which can stem from user problems, integration key (IK) issues, token exchange problems, malformed JWTs, or incorrect authentication endpoints—and service call errors, such as invalid access tokens, user membership issues, calling the wrong API endpoints, or violating specific restrictions for ISV 2.1 accounts. With this understanding of the inner workings of Docusign authentication, you are well equipped to get started implementing these different authentication flavors, ensuring secure and efficient application integration.

Go build your first Docusign integration! 

• Check out our Docusign eSignature Integration 101 series that guides you through the process of designing and building your first Docusign integration.

• Explore the Docusign Developer Center to learn more and sign up for a free developer account.

• Join the Docusign Developer Community for support and to connect with other developers.

• Check out our Partner Program, designed to support systems integrators and independent software vendors, no matter your business model. Whether you’re developing solutions for your own organization or for clients, our program has you covered.