Authentication Overview

Every API request must be authenticated. DocuSign provides three OAuth2 authentication grants and a legacy authentication mechanism. The purpose of each authentication scheme is to obtain a token that you can use to authorize calls to the DocuSign API.

Authentication Type Recommended Use Requires Browser
(Interactive)
Suppports Single Sign-on (SSO)
Two-Factor Authentication
Authorization Code Grant User applications Yes Yes
Implicit Grant User applications Yes Yes
Service Integration Authentication Service integrations One time for user consent Yes
Legacy Header Not recommended No No

The authentication flow you use depends on the kind of application you’re building. In general, there are two kinds of applications that use the DocuSign API:

  • user applications
  • service integrations

A user application is a client whose end users authenticate directly with DocuSign. These applications are typically web services, mobile applications, or desktop programs where the individual users can authenticate themselves on the DocuSign platform. As part of the authentication process, users give consent for the application to display, send, or sign envelopes from their account. For user applications, you should use the OAuth Authorization Code and Implicit grant types.

A service integration is a service that integrates directly with a DocuSign account. This kind of integration is typically reserved for backend services that authenticate on the DocuSign platform, without the involvement of an end user. For example, a backend application could be integrated into a line of business applications to automatically send non-disclosure agreements to new employees. Another example is an integration that connects an ECM system to DocuSign. For these types of applications, you should use Service Integration Authentication.

Legacy Header authentication was formerly recommended for service integrations. DocuSign recommends new service integrations be built with Service Integration Authentication.

Every authentication method requires an integrator key to identify your application as it makes API requests to the DocuSign platform. See Generating an Integrator Key to learn how to generate one.

OAuth Authorization Code Grant

The authorization code grant flow is part of the OAuth2 spec.

This grant type is suitable only for user applications because it requires an end user to authenticate with DocuSign.

In this authentication flow, your application uses its client id and secret key during the authentication process. Your application must be able to keep its secret key secure. Applications that use this authentication grant generally run on servers.

How the flow works:

  • Your application redirects the user to authenticate with the DocuSign authentication service.
  • DocuSign displays a login page. If the end user is already logged in, then the DocuSign authentication service may skip this step and the next.
  • The end user logs in.
  • The end user gives consent and acknowledges that they would like to use your application. This only happens once.
  • DocuSign completes the authentication steps and redirects the user back to your application. This returns an authorization code to your application.
  • Your application uses the authorization code to request an access token.
  • Your application uses the oauth/userinfo endpoint to find the user’s DocuSign account and base URI (API server) information.

Learn more about the Authorization Code Grant.

OAuth Implicit Grant

The implicit grant flow is part of the OAuth2 spec. This grant type is suitable only for user applications because it requires an end user to authenticate with DocuSign.

This grant type is reserved for client applications that are installed on an end user’s device. This could be a mobile app or desktop program. Because the app is installed on the user’s device, these applications are not able to maintain a secret key.

How the flow works:

  • Your application opens a browser window and redirects the user to authenticate with the DocuSign authentication service.
  • DocuSign displays a login page. If the end user is already logged in, then the DocuSign authentication service may skip this step and the next.
  • The end user logs in.
  • The end user gives consent and acknowledges that they would like to use your application. This only happens once.
  • DocuSign completes the authentication steps and redirects the user back to your application through a callback. This callback contains the access token in a hash fragment.
  • Your application uses the oauth/userinfo endpoint to find the user’s DocuSign account and base URI (API server) information.

Learn more about the Implicit Grant.

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.

Service integrations offer two ways to give consent:

  • User consent
  • Admin consent

How the flow works:

  • For user consent, the initial part of the flow is the same as Authorization Code Grant.

    For admin consent, the administrator gives 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, the goal is to obtain a user ID.

  • Your application uses its integrator key and the user ID to create a JWT token. The token is signed with your application’s private RSA key.
  • Your application uses the authorization code to request an access token.
  • Your application uses the oauth/userinfo endpoint to find the user’s base URI (API server) information.

Learn more about the Service Integration Authentication.

Legacy Header Authentication

Legacy Header Authentication is no longer recommended. DocuSign recommends new service integrations be built with Service Integration Authentication.

Legacy Header Authentication requires that the user credentials (email and password) be sent in an HTTP header with every request.

How the flow works:

  • Obtain the user’s email and password.
  • Use the credentials to create the X-DocuSign-Authentication header value.
  • Your application uses the login_information endpoint to find the user’s DocuSign account and base URI (API server) information.

Learn more about the Legacy Header Authentication.