Service Integration Authentication

Service Integration Authentication uses JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523) to create an access token. It is ideal for service integrations that do not involve a user agent like a browser or web view control. The result is an access token that represents the application or an impersonated user.

On this page

This method uses the DocuSign Authentication Service. See Working With the Authentication Service to learn more. Remember that the authentication service uses different host names for the production environment and the developer sandbox.

  • account-d.docusign.com for the developer sandbox
  • account.docusign.com for the production platform.

Requirements

To create the JWT token, your integrator key must include an RSA keypair. The service integration authentication flow uses the private RSA key to sign the JWT token and the public RSA key to verify the signature. You can generate a keypair when you create an integrator key, or you can add an RSA keypair to an existing integrator key.

Impersonation allows service integrations to acquire an access token that is equivalent to a user authenticating directly. Before an application can impersonate a user, the application must get consent directly from the user or from their account administrator.

Service integrations offer two ways to give consent:

  • User consent: An individual user with a DocuSign account can give consent that allows your application to use their account.
  • Admin consent: A domain administrator can give consent on behalf of all the users within the organization’s email domain. See the DocuSign Organization Administration guide to learn more about organizations.

In both cases consent requires a user or an administrator to interact with the DocuSign platform. Once you have consent, you application user will not need to interact with DocuSign.

User consent requires that an individual user approve that the application can use their account, and in the case of impersonation, to do so when the user is not logged in.

User consent can start with either the Authorization Code Grant or the Implicit Grant.

For example, if you’re using the Authorization Code Grant, you would direct the user to the following URL:

https://account-d.docusign.com/oauth/auth?
   response_type=code
  &scope=signature%20impersonation
  &client_id=230546a7-9c55-40ad-8fbf-af205d5494ad
  &redirect_uri=https://client.example.com/callback

Note that the scope is signature impersonation.

The user is asked to log in to their DocuSign account (if not already logged in), and then sees the consent dialog:

If the authentication is successful, the authentication service redirects the user to the redirect_uri. The callback contains a code:

HTTP/1.1 302 Found
Location: https://client.example.com/callback?
  code=eyJ0eX...ei0iLIFk3A

Use the code you got in the callback to request an access token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MjMwNTQ2YTctOWM1NS00MGFkLThmYmYtYWYyMDVkNTQ5NGFkOjMwODc1NTVlLTBhMWMtNGFhOC1iMzI2LTY4MmM3YmYyNzZlOQ==

grant_type=authorization_code&code=eyJ0eX...ei0iLIFk3A

Get the access token response:

{
  "access_token": "eyJ0eX...ZgbI2xzCoA",
  "token_type": "Bearer",
  "refresh_token": "eyJ0eX...XD8IDlL6GA",
  "expires_in": 28800
}

Use the access token with userinfo to get the user ID:

GET /oauth/userinfo HTTP/1.1
Authorization: Bearer eyJ0eX...ZgbI2xzCoA

For the service integration OAuth grant, you’re interested in the sub property which is the user ID you’ll need to create a JWT token.

{
  "sub": "b782664f-cf9d-abcd-87e5-a2181691e4a2",
  "name": "Jack Burden",
  "given_name": "Jack",
  "family_name": "Burden",
  "created": "2017-07-10T19:51:31.91",
  "email": "jack_burden@example.com",
  "accounts": [
    {
      "account_id": "0fc38253-8efc-feed-92a9-da3a05e07779",
      "is_default": true,
      "account_name": "Kingfisher",
      "base_uri": "https://demo.docusign.net"
    }
  ]
}

Now you have the essentials to create the JWT Token:

  • Consent from the user via the browser consent form
  • The user’s user ID
  • The application’s integrator key

Admin consent can only be done from DocuSign Admin and requires that DocuSign Organization Administration be enabled. Your organization must have an administrator and a validated email domain.

From the organization dashboard, click the Applications tile.

Click Authorize Application and choose an application from the drop-down menu. This menu lists every integrator key by name.

In the Add New Application dialog, enter the permissions you are granting the users of your application.

Typically this is signature impersonation.

Note that these permissions apply to every user who is a member of the organization’s reserved domains.

Creating the JWT Token

You need three things to create the JWT token:

See About JSON Web Tokens for a quick introduction to these tokens.

The header of the token always looks like this for a DocuSign service integration:

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

DocuSign supports only the RSA256 algorithm for signing.

The body of the token contains the following claims:

{
  "iss": "230546a7-9c55-40ad-8fbf-af205d5494ad",
  "sub": "1470ff66-f92e-4e8e-ab81-8c46f140da37",
  "iat": 1499293893,
  "exp": 1499297493,
  "aud": "account-d.docusign.com",
  "scope": "signature"
}

DocuSign uses the following claims. All are required.

Claim Description
iss The integrator key (or client ID) of the application.
sub The user ID. (This is a UUID.)
iat The “issued at” time for the token in the Unix epoch.
exp The expiration date for the token in the Unix epoch. This value is clipped at iat + 3600 (one hour). Shorter times are honored, but longer times are clipped to 3600 seconds.
aud The server address. Either account.docusign.com or account-d.docusign.com.
scope A space-separated list of permissions the application is granted. Valid values: signature, impersonation

The JWT token may contain other claims. These are ignored.

In general, you use a JWT library, along with your application’s private RSA key, to generate and sign the token. To learn how a JWT token is assembled, encoded, and signed see About JSON Web Tokens

An encoded and signed JWT token looks like this. The linebreaks after the periods that separate the header, body, and signature parts are for clarity.

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.
eyJpc3MiOiIyMzA1NDZhNy05YzU1LTQwYWQtOGZiZi1hZjIwNWQ1NDk0YWQiLCJzdWIiOiIxNDcwZmY2Ni1mOTJlLTRlOGUtYWI4MS04YzQ2ZjE0MGRhMzciLCJpYXQiOjE0OTkyOTM4OTMsImV4cCI6MTQ5OTI5NzQ5MywiYXVkIjoiYWNjb3VudC1kLmRvY3VzaWduLmNvbSIsInNjb3BlIjoic2lnbmF0dXJlIn0.
Cal92sXfWU23vpbY07cHcuMAL3jKhrmxVdlhRkgWyl1QtTfJvcvvCHQACLDw-b-IK-IlOH7RDrrywO5yEdpaZtDSMaXfnhfofmp4J0Ogd33mTv1u-Py8Lt-Pppd8siF7aiDQdVqwWEL03hTkPTvnzXoBhUULduAwZfCo1mTeaZ4S6jgT0nElYgYTIS7gypxsuc4Bt3fSFobpgIrWckJ894XppFPPFmafXUvF6SrIuBFLgsYz1DLo6Dphdj3WamOsxi4pNOeWUsecM93pWKPIWQV2LI_b7yhfhDK3z8RfnZvouny6_KwGd6YCjEqdJEYH4O-vwVpmwDiVa1mrNoZugw

Requesting the Access Token

To request an access token, send a request to the authentication service using the JWT token like this. The assertion body parameter contains the JWT token.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=eyJhbG...muZQtsmug
Parameter Description
grant_type Must be urn:ietf:params:oauth:grant-type:jwt-bearer
assertion The JWT token you generated

A successful response will contain the access token.

{
  "access_token": "eyJ0eX...AnHDQ0bbA",
  "token_type": "Bearer",
  "expires_in": 3600
}
Property Description
access_token The access token you will use to make API calls.
token_type The kind of token. Always Bearer.
expires_in The number of seconds before the access token expires.

Once you have the access_token, use it in in the Authorization header whenever you call an API endpoint. Note that you must include the token type in the header:

Authorization: Bearer eyJ0eX...AnHDQ0bbA

Obtaining the Base URI

The first thing you should do after getting your access token is to use the /oauth/userinfo endpoint to get user’s account and base URI information that you’ll use to access the DocuSign API.

GET /oauth/userinfo
Authorization: Bearer eyJ0eX...AnHDQ0bbA

The response will look something like this:

{
  "sub": "25c0e33e-9177-444e-aaeb-af61a882b383",
  "name": "Admin User",
  "given_name": "Admin",
  "family_name": "User",
  "created": "2017-07-05T18:11:07.2",
  "email": "admin@orobia.net",
  "accounts": [
    {
      "account_id": "624e3e00-36cb-4bcf-a4af-43918c520dab",
      "is_default": true,
      "account_name": "LoanCo",
      "base_uri": "https://demo.docusign.net",
      "organization": {
        "organization_id": "96e994fa-b330-44ba-959b-c5fe9d1ccd10",
        "links": [
          {
            "rel": "self",
            "href": "https://account-d.docusign.com/organizations/96e994fa-b330-44ba-959b-c5fe9d1ccd10"
          }
        ]
      }
    }
  ]
}

Renewing Access Tokens

The expires_in property of the access token response specifies how many seconds the access token is good for. To get a new access token, create a new JWT token, and get a new one.

Access tokens expire after one hour (3600 seconds). When the access token expires, create a new JWT token, and get a new one.

Instead of waiting for an access token to expire, DocuSign recommends that you refresh the access token when one half to three quarters of the expires_in time has elapsed. For example, if the expires_in value is 3600 seconds, you should get a new token after 1800 to 2700 seconds. When you first get the access token, use the expires_in value to calculate an expiration time. Store this expiration time in the user’s session. Before making a call to the DocuSign API, check the current time against the expiration time. If it is within the threshold, create a new JWT token to get a new access token.

Users and organizations can revoke consent for an application to use their account.

JWT tokens become invalid when consent is revoked.

Individual users can revoke consent through the DocuSign webapp.

  1. From the Profile Menu choose **My Preferences.
  2. Choose Connected Apps from the side bar.
  3. Scroll to the Applications with Access to DocuSign section.
  4. Click Manage Apps.

To revoke consent from applications that use Admin Consent, click the Applications tile from the organization dashboard.

Choose Revoke from the Action menu of the application you want to revoke.

Users who are members of the organization’s reserved domains cannot revoke consent individually.

Errors

The POST /oauth/token endpoint can return can return the following errors:

Response Code Response Body Description
400 {"error":"consent_required"} The user or administrator hasn’t granted or has revoked consent. You may have created a valid JWT token for a user who hasn’t given consent.
400 {"error": "invalid_grant"} The JWT token was valid, but some of the claims were not.