> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# JWT Grant implementation and best practices

> Provides best practices and guidance for implementing JWT Grant in your integration.

This topic describes the best practices for designing your app to implement JWT Grant, focusing on consent and workflow rather than covering the detailed mechanics of getting an access token. For details on how to get an access token using JWT Grant, see [How to get an access token with JWT Grant](/platform/auth/jwt-get-token).

## Obtain consent

Integrations that implement JWT Grant must first handle *consent* before any JWT exchange for an access token can take place. There are two types of consent:

* **Admin consent**, where a Docusign administrator (an organization management administrator, not an eSignature account administrator) may grant consent on behalf of all claimed domain users in their Docusign organization.
* **Individual consent**, where each individual user must be prompted to grant consent prior to obtaining the first access token on behalf of that user.

**Admin consent** requires the customer to have the Access Management product as part of their Docusign plan and to have claimed a domain. Because the Access Management product is an add-on and is not in use by all customers, it is an optional approach to fulfilling the consent requirements. Admin consent works in one of two ways, depending on the relationship between the integration and the account owner:

> **Warning**
>
> **ISV best practice**: When you implement Admin consent for your app, it is recommended to also build an individual consent path alongside it. Because Access Management is required for admin consent, it may require Docusign customers to purchase additional services in order to use this functionality and can create a barrier to entry for your integration.

* **Customer-owned integrations where the integration key is managed by admins of an account linked to the customer organization**: These integrations should use [admin consent for internal applications](/platform/auth/consent/obtaining-admin-consent-internal). In this flow, a Docusign administrator can grant consent from within the Docusign organization management app on behalf of all organizational users that are under a claimed domain.
* **ISV-owned integrations that are licensed by the ISV’s customers**: These integrations should use [admin consent for external applications](/platform/auth/consent/obtaining-admin-consent-external). In this flow, a Docusign administrator grants consent on behalf of the organization’s domain users.

  **Note:** For external integrations, consent cannot be granted from the UI. Instead, the integration must begin the admin consent flow instead of the individual consent flow that is presented to the Docusign administrator by default.

The following diagram shows the logical steps your integration should implement for integration setup and configuration. This includes the optional use of admin consent:
![Shows the logical steps your integration should implement for integration setup and configuration](/_fern-files/_img/0cd8535e73093c132fa958f11f48fedcf92e01618a00cb2f6e07f65e3660109e.webp)

It is important to note that there are **two different methods of granting admin consent**, one for [internally developed integrations](/platform/auth/consent/obtaining-admin-consent-internal) and one for [third-party integrations](/platform/auth/consent/obtaining-admin-consent-external). The implementation logic shown in the diagram also highlights the following best practices:

* **It handles obtaining both admin and individual consent**. The easiest way to obtain consent for large numbers of people is via admin consent, but this solution is not always available for all users.  There may be part of the account membership base that is not under the organization’s domain and therefore these users must grant consent individually. Your integration should attempt to gain consent using admin consent, then fall back to using individual consent if necessary.  For ISV integrations in particular, not all customer accounts will have Access Management, therefore individual consent is a must to cover these customers.
* **It requires that the user setting up organization consent be an administrator of the organization**, rather than an eSignature account admin.

## Implement JWT Grant

The following diagram shows the logical steps your integration should implement to use JWT Grant:![Shows the logical steps your integration should implement to use JWT Grant](/_fern-files/_img/0bc52eca211afa7863317b6c6675609328a1a79737c35fcada24be091196a929.webp)

> **Warning**
>
> Your integration should handle the possibility of losing user consent. Users and admins may choose to revoke consent at any time.

#### Requirements for implementation

* You must configure and securely store a redirect URI and RSA key pair for your integration.
* Your integration must store a GUID user ID to use for account-wide API access such as administrative tasks or account-wide envelope retrieval.

#### Step-by-step flows for ISV integrations

The following workflow describes best practice considerations and steps your integration should implement to support **admin/system user setup**:

1. As the eSignature administrator that is configuring the integrated application, collect the **API account ID**, **account base URI**, and **user ID** of the admin user that will be used for all account-wide and administrator needs of the integration. You can find these values in the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page under **Settings** for the desired eSignature account.
2. Determine the consent flow option to use.

   1. If the client wants to use the [organization administrator consent for external applications](/platform/auth/consent/obtaining-admin-consent-external) flow, make sure that a Docusign administrator takes the following actions:

      a. Use the admin consent for external applications flow to obtain consent, requesting the `openid` scope, which enables you to grant consent to an external app on behalf of your users. The organization administrator will be prompted to log in and grant consent on behalf of their organization’s domain users.
      b. The organization administrator will be sent to your integration’s defined redirect URI. Other than notifying you that consent was granted, this response is not used further. Consent has been granted for all users of the organization’s claimed domains.
   2. If the customer does not wish to use organization consent or if they do not have access to Docusign Admin, use the [individual consent flow](/platform/auth/consent/obtaining-individual-consent)  to get the eSignature account admin’s consent. Store the admin’s user ID for later use.

The following workflow describes the best practice considerations and steps your integration should implement to support **runtime user API calls**:

1. Retrieve the user’s Docusign user ID from your app users data store.

   1. If no user ID is found (such as when you run the workflow for the first time), retrieve the admin user’s user ID.
   2. Create a JWT and impersonate the admin user by combining their user ID and RSA key pair signature as described in [How to get an access token with JWT Grant](/platform/auth/jwt-get-token).
   3. Exchange the admin JWT for an access token and use it to make the following API call, using the intended app user’s email address:
      `{base API URL}/{accountId}/users?email={email}`
   4. Parse the response to extract the user ID. For efficiency, store the user ID with this app user’s data.
2. Create a JWT and impersonate the app user by combining their user ID and RSA key pair signature as described in [How to get an access token with JWT Grant](/platform/auth/jwt-get-token).
3. Submit the JWT to receive an access token in the response. If storing the access token, be sure to use secure, temporary storage, such as binding to a server-side session.
   If impersonation fails, use the [individual consent flow](/platform/auth/consent/obtaining-individual-consent) to prompt the user to provide consent, then retry.

   1. Prompt the user to grant consent by redirecting their browser to the `/oauth/auth` endpoint, providing your desired authentication parameters.
   2. If successful, resubmit your JWT.
4. Use the access token to authenticate your API calls.
5. When the token expires, create a new JWT and use it to get a new access token.

## Next steps

* For a step-by-step walkthrough of how to get an access token using this grant, see [How to get an access token with JWT Grant](/platform/auth/jwt-get-token).
* Learn more about how to [Choose an OAuth type](/platform/auth/choose).