DocuSign Developer FAQs - General Administration and Authentication

DocuSign Developer FAQs ‐ General Administration and Authentication

The following are answers to some of the most common questions we receive about General Administration and Authentication. For Developer FAQs on other topics, see the DocuSign Developer FAQs ‐ Table of Contents, or the links under References at the end of this page.


General Administration


Authentication


General Administration

Why am I seeing the error “User Lacks Permission” when retrieving form data through eSignature REST API?

This error means that the “Allow the sender to download form data” setting is disabled. To configure this in the eSignature web application navigate to Settings > Sending Settings, and enable the setting Allow sender to download form data.


No. The Legal Disclosure's behavior can only be changed in the eSignature web application, by going to Settings > Legal Disclosure. For more details, see this guide.


Can I transfer Integration Keys between accounts?

Yes, although in most cases there is no need. An integration key is tied to a particular account for management purposes, but that key can be used to make API calls on any account once properly authenticated.

If an integration key does need to be transferred between two accounts, DocuSign Support can do so with authorization from administrators on both the current account and the destination account. If one user is an administrator of both accounts, they can sign for both roles.

To request an integration key transfer, open a case with DocuSign Support and provide the following:

  • Environment (Demo or Production):
  • Integration Key:
  • Source account ID:
  • Email address of source account admin:
  • Destination account ID:
  • Email address of destination account admin:

Support will send an envelope requesting authorization, and once that is signed the key will be transferred. Note that keys are not "transferred" between Demo and Production - if a key needs to be enabled in the Production environment, it will need to go through the Go Live process.


Authentication

All integrations with DocuSign APIs must authenticate in order to make API calls.


What types of API authentication are supported? Are examples available?

DocuSign's eSignature REST API supports and has examples for Authorization Code GrantImplicit Grant and JSON Web Token (JWT) Grant authentication.


How can I find my user ID for authentication?

While you can use the API to query for the user ID for any member of your account, you need one user ID to get started with JWT Authentication. To find your own user ID, navigate to Settings > Apps and Keys. To find the user ID for any other member of the account, navigate to Settings > Users > Edit.


Detailed documentation on application consent is available in the Developer Center. Individual consent is obtained by directing the user to an authorization URI. An organization administrator can grant blanket consent to an application through the Organization module; however, this blanket consent only applies to users with email addresses under domains claimed by the organization.


What is a refresh token, and how is it used?

Refresh tokens are used in the Authorization Code Grant workflow to generate new authorization tokens without requiring end-user interaction. Standard refresh tokens last for 30 days from the initial consent grant. If the extended scope was granted, new refresh tokens can be generated as long as the currently held refresh token is less than 30 days old. Full documentation is available in the Developer Center.


Can I use the same integration key, client secrets, or RSA key pairs between the developer sandbox and production environments?

No. During the Go Live process, an integration key is transferred from developer sandbox to production. While the key's GUID will not change, the developer sandbox and production environments are separate instances, so new client secrets and RSA keypairs must be generated.


What scopes are supported in the eSignature API?

For the eSignature REST API, the scopes are signature, extended, and impersonation:
  • signature — Allows your application to create and send envelopes and obtain links to start signing sessions.
  • extended — Without this scope, a refresh token will last 30 days from the initial consent grant. With this scope, new refresh tokens can be generated indefinitely. This scope may only be used in Authorization Code Grant authentication.
  • impersonation — Allows your application to access a user’s account and act on their behalf even when that user is not present. This scope is only used by JWT Grant authentication. 

Multiple scopes can be requested at once, separated by spaces in the authorization URL.


Can an OAuth access token's lifetime be changed?

No. JSON Web Token (JWT) grant tokens have a fixed lifetime of one hour and the Authorization Code Grant and Implicit Grant access tokens have a fixed lifetime of eight hours. If your application makes an API call with an expired token, it will encounter an authorization failure error and must request a new token to proceed.


Does DocuSign have OAuth code examples?

Yes. You can find OAuth code examples in our Developer Center:


Detailed documentation on application consent specific to the JWT Grant is available in the Developer Center.

JWT consent can be granted administratively by the system administrator if your account includes the Access Management feature (previously known as the “org admin” feature) and you have claimed the email domain of the impersonated users’ email addresses.

JWT consent can also be granted individually; each user who will be impersonated must grant permission themselves.

To grant consent individually, use the same consent process as Authorization Code Grant with a few exceptions:

  • The scopes must include signature and impersonation (and perhaps other scopes too, depending on the API you’ll be using).
  • Don't use the authorization code that is returned to request a token. Just ignore it: the important side effect is that the user has granted consent to your integration key.
  • The consent is stored on DocuSign servers until it is revoked by a user, so typically, you only need to get user consent once.

When using JWT authentication, how do I troubleshoot an invalid_grant or other errors?

The invalid_grant error is a generic error response that means something is incorrect in the JWT assertion. In order to determine what is wrong, refer to the error_description parameter in the response. If the error_description isn't readily available in your application, we recommend setting up error logging that captures the full error response.

Authentication error responses:

  • consent_required: If using individual consent, make sure consent has been granted for the desired scopes. The signature impersonation scope is the minimum required for JWT authentication, but other scopes may be necessary for Rooms or Admin functions.
  • invalid_subject or user_not_found: Something is likely wrong with the sub (subject) value in the assertion. Confirm that the value is a valid GUID user ID (not an email address) of a user that is active in the relevant environment.
  • Issuer_not_found: The integration key in the iss (issuer) parameter is unavailable in the current environment. This can also mean a mismatch in the aud (audience) value and the environment being hit: for example, using an aud value of account.docusign.com while requesting a token from https://account-d.docusign.com/oauth/token.
  • no_valid_keys_or_signatures: This error covers several cases:
    • There is an issue with the private key used to sign the assertion (for example, using a demo key in the production environment).
    • The assertion is missing an exp (expiration) parameter
    • The aud (audience) parameter is invalid - confirm the audience value is exactly account.docusign.com or account-d.docusign.com with no https:// prefix or trailing slash (/).
    • An nbf (not valid before) parameter is defined, and that time has not been reached. The nbf parameter is optional and can be removed from the assertion, but if it is present, it must be a time in the past.
  • expired_grant: The assertion has expired. The exp (Expiration) parameter must be a time in the future.

Admin consent requires a claimed email domain, and only applies consent to users with an email address in that domain. So in order to grant Admin consent to act as user@example.com, the domain example.com must be claimed in your organization, and signature impersonation scopes must be granted under the Applications tab of DocuSign Administration (not DocuSign eSignature Administration).

Once the domain claim is confirmed, there can be a delay of a few minutes before it is recognized by DocuSign. If the error persists after that, we recommend clearing your browser cache.


Why am I getting UserNotFound when I make an UserInfo call with a valid token?

This is due to a known issue: API - UserInfo call returns empty array for specific user. Note that, while that article refers to an empty UserInfo response, the UserNotFound / "The user is not found in DocuSign" response is due to the same underlying behavior and has the same solution. Please open a DocuSign Support case referencing that article and providing the relevant information.


How do I fix an error with getting an auth token using the JWT flow?

Error Message: DocuSign.eSign.Client.ApiException: 'Error while requesting server, received a non successful HTTP code Error with response Body:'

Accompanied with this error is often one of three faults:

  • {Consent_Required}
    • Consent has been revoked
    • Consent has never been supplied
    • User / Consent is in a bad state, needs to be removed / reapplied

Please review the following for more information on Obtaining consent.

  • {Invalid_Grant}
    • The error description often reveals the source:
      • IAT (Timestamp the token is issued at) Is a time > 1 hour before the request is made
      • Exp (Expiration) value is in the past or before IAT time
    • RSA key is invalid
      • -----BEGIN RSA KEYPAIR----- / End lines removed
      • The PEM file has been corrupted
      • The RSA key is no longer properly registered within DocuSign and needs reissued
      • AUD line points to Demo over Prod or vice versa.
  • {Internal_Server_Error}
    • Invalid JWT assertion
    • RSA key is invalid
    • AUD parameter has an invalid value -- this value should specifically be account.docusign.com for Production, account-d.docusign.com for Demo. These values cannot containing a leading http://, https://, or trailing /
    • For example:
      • account-d.docusign.com = yes
      • https://account-d.docusign.com = no
      • account-d.docusign.com/ = no
      • ApiClient apiClient = new ApiClient("https://demo.docusign.net/restapi");
      • API Client being used needs to have calls pointed to {endpoint}.docusign.net/restapi

Please see the following on implementing JWT flow and assertion. Call the UserInfo endpoint to determine the base URI and account information to interact with the DocuSign API service.


When a user grants an individual OAuth consent or an organization administrator grants organization wide OAuth consent to your application, it never times out. The consent can be revoked however. The access token returned by DocuSign from a JWT flow expires in one hour. Attempting to set a longer expiry in the JWT assertion will have no effect on the token's lifespan. If your application uses the access token for multiple calls, you will need to store the expires in time and check the time before making API calls. The CheckToken() functions in our code examples demonstrate this.


Can OAuth tokens be revoked?

DocuSign OAuth tokens cannot be revoked. Revoking application consent will prevent new tokens from being generated, but will not invalidate existing tokens.


Why is my legacy header authentication failing when I enable two factor authentication (2FA)?

This is working as designed. Legacy header authentication and 2FA are mutually exclusive. Using an OAuth authentication flow will work with 2FA enabled.


While Admin Consent allows you to bypass the need for each individual user to provide consent, there are a couple of hurdles that must be cleared before you can successfully impersonate a user:

  1. The email domain of the user in question must be claimed by your organization in order for admin consent to apply. Subdomains are seen as distinct entities, so a user on an @mail.example.com email address won't automatically have consent granted when @example.com is claimed.
  2. The correct Scopes must be granted. Impersonation is always required for JWT authentication, signature covers the standard eSignature REST API, and other scopes are relevant to other functions.
  3. Admin Consent requires access to Organization functionality. If your account plan does not include this, reach out to your account team to discuss. For steps on how to claim a domain, see this guide.

Does DocuSign RestApi support MASSL authentication?

No, DocuSign does not support Mutual SSL Authentication.

DocuSign supported SSL


Why am I seeing the error "the redirect URI is not registered properly with DocuSign"?

This error typically means one of the following requirements was not met:

  1. You must define at least one redirect URI to implement any authentication scenario in your integration key configuration.
  2. In the request URL the value supplied for redirect_uri must exactly match one of the defined ones in the integration key configuration.
  3. The redirect URI must include the full path to the host including protocol. For example: https://localhost:8080
  4. It can take up to 5 minutes for newly saved URIs to take effect.
  5. Fragment indicators (#) are not allowed in the URI as per OAuth requirements.

References