Authentication Overview

Every API request must be authenticated. DocuSign provides two 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.

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 Legacy Header 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 baseUrl (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 baseUrl (API server) information.

Learn more about the Implicit Grant.

Legacy Header Authentication

Legacy Header Authentication is used for Service Integrations. It requires that the user credentials (email and password) be sent with every request.

The user credentials are sent as a header item with an HTTPS connection.

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 baseUrl (API server) information.

Learn more about the Legacy Header Authentication.

Summary

Use the following table to help you decide which kind of authentication flow is best for your purpose.

Authentication Type Recommended Use Requires Browser
(Interactive)
Requires confidential data on a server Uses Authentication Service OAuth Access Token
Authorization Code Grant User applications Yes Secret key must be protected Yes Limited life, may be refreshable
Implicit Grant User applications Yes No Yes Not refreshable
Legacy Header Service integrations No Account credentials must be protected No None

Although you can use any authentication method for a user application, only the OAuth flows enable you to generate an access token without handling the user’s email and password within your app. All new user applications for the DocuSign Signature REST API should use an OAuth flow.