DocuSign API JWT Grant Flow: Service Integration Auth Guide

The JWT Grant flow is DocuSign's OAuth 2.0 authentication method for service integrations: automated backends that call the DocuSign API as one specific user, without that user logging in. You register an integration key, add an RSA public key on the Apps and Keys page, collect one-time consent from the user being impersonated, then sign a JWT with your private key and POST it to DocuSign's /oauth/token endpoint in exchange for an access token. That token is valid for one hour, the flow never issues a refresh token, and when the token expires your integration simply builds and signs a new JWT and exchanges it again. This guide covers each step, the consent rules, the token mechanics, and how to choose between JWT Grant and the Authorization Code grants. If you are newer to the platform, a general DocuSign API walkthrough is a good warm-up before diving into authentication.

What the JWT Grant Flow Solves for Service Integrations

DocuSign's documentation splits integrations into two families. User integrations act on behalf of a person who is present and logs in; they authenticate through the Authorization Code Grant flows. Service integrations connect directly to a DocuSign account and obtain permission to impersonate, meaning act as, a specific user on a long-term basis without that user being present.

The example DocuSign itself gives: a service that watches for new hires and automatically sends onboarding documents from an HR alias or manager account, so nobody has to click Send for each employee. Service integrations are heavily automated and call the platform frequently with no direct user interaction, which is exactly the scenario JWT Grant was built for.

DocuSign lists concrete advantages for this flow: system accounts can perform operations for any user in a consenting organization whether or not that user is present; large user bases become manageable when paired with DocuSign Admin; and the RSA key pair provides strong security. The trade-offs are real, too. Your integration may need to support multiple consent paths (admin consent plus individual consent for people outside your domain), you must look up and store an account-wide user ID for general account access, and if you are not using one of the DocuSign SDKs you will need a cryptographic library to build the JWT. For a broader view of what automation unlocks, see the benefits of integrating e-signature APIs into business software.

Prerequisites: Integration Key, Redirect URI, and RSA Key Pair

DocuSign's documented prerequisites for JWT Grant come down to three items:

1. An integration key, which identifies your integration and links to its configuration values. You create it on the Apps and Keys page.
2. A redirect URI registered to that integration key. In the JWT flow the redirect URI is used only during consent; the authorization code that arrives there is not used afterward.
3. An RSA key pair. The public key is added to your integration's configuration, and the private key stays with your application.

Two details are worth flagging. First, an integration key supports a maximum of five RSA key pairs, so if you already have five you must delete one before adding another. That ceiling is also your rotation budget: add the replacement key first, switch your code to it, then retire the old key. Second, 2048-bit is the RSA size used in DocuSign's published examples, and the private key file belongs in a secrets manager, not in source control.

How to Get an Access Token with JWT Grant, Step by Step

Step 1: request consent. Before any API call, the user your app will impersonate must grant permission. You open DocuSign's authorization endpoint in a browser with your integration key as the client_id, your requested scopes, and your registered redirect_uri. The user signs in and accepts, and from that point your app can impersonate them via JWT Grant. The query parameters returned to your redirect URI, including the code value, are not used in the JWT flow.

Step 2: create the JWT. Build the assertion from your integration key, the user ID of the impersonated user, and the correct audience for your environment, then sign it with the RSA private key. The next section breaks down every field.

Step 3: exchange the JWT for an access token. POST it to the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer:

curl --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=YOUR_JSON_WEB_TOKEN" \

--request POST https://account-d.docusign.com/oauth/token

For the developer (demo) environment the endpoint is https://account-d.docusign.com/oauth/token; for production it is https://account.docusign.com/oauth/token. A successful response contains your access token.

Step 4: get the user's base URI. API calls need the access token plus a base URI unique to the user you are acting for. Call the /oauth/userinfo endpoint with a Bearer authorization header; it returns the accounts the user belongs to, and you take the account_id and base_uri values from the response. DocuSign enforces hourly limits on /oauth/userinfo requests per user ID and per integration key, so cache these values rather than calling the endpoint on every request.

The JWT Assertion: Header, Claims, and Signature

A DocuSign JWT is three JSON blocks, encoded and separated by period characters. The header specifies the algorithm:

{"alg": "RS256", "typ": "JWT"}

The body carries the claims that identify who is asking and whom to impersonate:

{"iss": "", "sub": "", "aud": "account-d.docusign.com",

"iat": , "exp": ,

"scope": "signature impersonation"}

Field by field:

• iss: your integration key, also called the client ID.
• sub: the user ID of the user being impersonated.
• aud: account-d.docusign.com in the demo environment, account.docusign.com in production.
• iat and exp: the issue time and expiration time as Unix epoch values. DocuSign's sample uses an expiration roughly one hour ahead of issue.
• scope: "signature impersonation" for signing workflows.

The signature is RSASHA256 computed over the base64url-encoded header and body, using your private RSA key. You can assemble the assertion by hand with a JWT library, or let a DocuSign SDK handle it; the official SDKs wrap the whole exchange in a single request call. Whichever route you take, a mismatched aud (demo versus production) or an unsigned assertion will fail at the token endpoint.

One more planning note: the account-wide user ID used for general account access is not always the value you start with. DocuSign's docs point out that obtaining it requires additional API calls or implementation for storing and looking it up, so budget a small provisioning step.

Consent: The One-Time Gate Before Impersonation

Consent is what separates a legitimate service integration from an unauthorized one, and DocuSign treats it seriously. There are two documented paths.

Individual consent: each impersonated user opens the authorization URL, signs in, and clicks Accept. DocuSign's docs note that after accepting, the user's browser may display a page that cannot load; that message can be ignored and the tab closed. Consent remains in effect until it is revoked.

Admin consent: administrators can grant consent for an organization through DocuSign Admin, for internal applications and for external applications. Because not everyone who works with an organization is on its domain or has access to DocuSign Admin (DocuSign's own example is contractors), integrations commonly need to support both admin and individual consent.

Consent is also granted per environment. Demo consent does not carry over to production, so repeat the consent step after you switch to production endpoints.

Token Lifetime: One Hour, No Refresh Token

This is the part that surprises teams coming from other OAuth integrations. The access token issued through JWT Grant expires after one hour, and the flow does not provide a refresh token. When the token expires, your integration must generate a new JWT and exchange it for a new access token. In practice that means:

• Treat token requests as routine, not exceptional. A token fetch roughly once per hour per impersonated user is the expected cadence.
• Cache the access token for its useful life, and handle expiry with a retry that re-requests the token rather than failing the business transaction.
• Build a fresh assertion with a current iat each time instead of reusing a stale JWT.
• Protect the private key. Anyone holding it can impersonate every consenting user of the integration, which DocuSign explicitly describes as a high degree of granted trust. Layer account-level protections as well, such as enabling two-factor authentication for signers and admins on the accounts your integration touches.

Choosing an Authentication Flow: JWT Grant vs. Authorization Code Grants

JWT Grant is not the only door into the DocuSign API, and it is the wrong door for interactive apps. A static API key is not among DocuSign's documented authentication options; the platform authenticates through OAuth 2.0 grants. So the practical decision is between JWT Grant and the Authorization Code Grants:

Use JWT Grant when all operations run under a system or admin login, or when you manage large numbers of users via DocuSign Admin. Use an Authorization Code Grant when your app needs each end user to sign in and act as themselves. DocuSign's guidance is direct on this point: if your integration does not need impersonation access or automated operations, use an Authorization Code Grant instead. One budgeting note: authentication design also shapes cost, because token churn and API call volume feed into DocuSign API pricing models.

JWT Grant Implementation Checklist for Service Integrations

Before go-live, work through this checklist:

• Integration key and redirect URI created on the Apps and Keys page
• RSA key pair generated (2048-bit), public key uploaded, private key stored in a secrets manager
• Consent collected: individual consent URL exercised by each impersonated user, or admin consent via DocuSign Admin
• Consent repeated separately for the demo and production environments
• iss (integration key), sub (user ID), and aud (per environment) wired into JWT construction
• Token request targets the correct endpoint: account-d.docusign.com for demo, account.docusign.com for production
• /oauth/userinfo results (account_id, base_uri) cached to respect hourly limits
• Access token refreshed by building a new JWT each hour; no refresh token expected
• 401 handling retries with a fresh token instead of failing the transaction
• Key rotation plan respects the five-key-pair ceiling: add the new key, switch, then remove the old one

A Simpler API Path for APAC Workflows: Nota Sign

Authentication plumbing is where APAC expansion plans usually meet reality: a platform that handles a US-centric workflow smoothly can stumble on regional identity and assurance requirements. Nota Sign, the global e-signature platform of FaDaDa, is built APAC-first, with native iAM Smart support in Hong Kong, Singpass integration in Singapore, and SES, AES, and QES signature levels for workflows that need eIDAS-style assurance.

If you are still shortlisting platforms, our comparison of the best e-signature REST APIs for developers and the walkthrough of a China e-signature REST API for software developers cover the field. To scope an integration around your regions and assurance levels, reach the Nota Sign team on the contact page.