Skip to navigation
Platform 101Authenticate

JSON Web Token (JWT) Grant authentication

View as Markdown

JSON Web Token (JWT) Grant is an OAuth 2.0 flow that is used to grant an access token to service integrations. Service integrations differ from user integrations (which should authenticate through the Confidential Authorization Code Grant or Public Authorization Code Grant flows) in that:

  • A service integration integrates directly with a Docusign account and does not authenticate every end user. Instead, the integration obtains permission to impersonate (act as) a specific user on a long-term basis without that user being present. This differs from acting on behalf of a user (as in the Authorization Code and Implicit Grants) in that it does not require the user to be present and logged in. For example, a service integration might use an HR alias or manager’s account credentials to send onboarding documents whenever a new employee is hired by a company.
  • Service integrations are often heavily automated, and will frequently call the Docusign platform without direct user interaction. For example, the service integration mentioned above would likely automate the process of sending the onboarding documents so that the HR alias or manager would not need to explicitly send the documents each time a new employee was hired.
  • The JWT Grant flow does not grant a refresh token.

In the JWT Grant authentication flow, your integration posts a JWT to the Docusign authentication service, asserting its credentials and providing the data of the user that it wishes to impersonate. Docusign validates that the assertion is signed and that your integration has the consent to act on behalf of the user, then issues an access token that allows you to call Docusign APIs. Consent to act on behalf of a user is given through a consent process. There are multiple methods for granting consent, depending on your use case. See Obtain and revoke consent for details.

Flow diagram showing the steps in JWT authentication for your user, your app, and the Docusign server

You should use JWT Grant to authenticate if:

  • All of your users will use a system or admin login.
  • You are managing large numbers of users via Docusign Admin

Advantages of using JSON Web Token Grant

  • You can use system accounts to perform operations on behalf of any user within a consenting organization, regardless of whether they are present.
  • You can easily manage large user bases when coupled with Docusign Admin.
  • The RSA key pair provides excellent security.
  • After gaining consent, JWT Grant doesn’t require a user to be present. This enables you to easily create a new token.

Disadvantages of using JSON Web Token Grant

  • Integrations implementing the JWT Grant flow may need to support multiple ways to get consent:

  • Your integration must obtain and use an account-wide user ID that is used for general account access. This requires additional API calls or implementation for storing and looking up this value.

  • When not using one of the Docusign SDKs, implementing JWT Grant requires a cryptographic library to build the JWT.

  • The access token granted by the JWT Grant flow expires after one hour, and no refresh token is provided. After the token expires, you must generate a new JWT and exchange it for a new access token.

  • Because an integration using JWT Grant authentication may impersonate one or more users at will, it can involve a high degree of granted trust. If your integration does not need impersonation access or to perform automated operations, use the Public Authorization Code Grant or Confidential Authorization Code Grant flows instead.

Next steps