Skip to navigation
CLM API 101

Authentication Overview

View as Markdown

Developing with the CLM API is only available for CLM customers with a production account. To purchase a plan to gain access to the CLM API, contact Docusign Sales.

Before your application can make calls to the CLM API, it must authenticate and obtain an access token. This access token proves your app’s identity and authorization. You must submit the token with each request.

You can use any Docusign-supported OAuth2 authentication workflow to obtain an access token and make calls to the CLM API: Confidential Authorization Code Grant, Public Authorization Code Grant, Implicit Grant, or JSON Web Token (JWT) Grant. Service integrations may use Confidential Authorization Code Grant or JWT Grant, while mobile apps may use Public Authorization Code Grant or Implicit Grant.

Note: Salesforce clients authenticate by using JWT Grant. For details, see Salesforce Client Authentication.

For an overview of these grant types and to determine the best grant type to use for your app, see Authentication in the Platform 101 documentation.

Prerequisites

Before you can use the Docusign CLM API, you need:

  1. A Docusign eSignature developer account and a Docusign CLM account.
  2. An integration key that identifies your app.
  3. A defined redirect URI for your integration key. This is the URL to which Docusign will redirect the user’s browser after authentication is complete.
  4. You must also have configured your app correctly for the OAuth type you want to use. For details, see the instructions for the grant type you want to use under Next steps.

Required scopes

One of the differences between authenticating with the CLM API and the eSignature API is that, when you request an access token for your OAuth2 scenario, you must request a special CLM API scope during the authentication process. You can combine CLM scopes with eSignature API scopes.

You can choose from the following CLM scopes:

ScopeDescription
spring_readAllows read access to all objects, including downloading documents.
spring_writeAllows write access to all objects, including uploading documents.
contentAllows read and write access only to document content. This scope grants you access to download and upload documents, but does not grant access to other resources. If you are already requesting the spring_read and spring_write scopes, you don’t need to also request the content scope.

Note: The impersonation scope is also required when using the JWT flow.

Only request the scopes you need for your application.

  • Using Authorization Code Grant, you request scopes when you make the authorization code request.
  • Using Implicit Grant, you request scopes when you make the access token request.
  • Using JWT Grant, you request scopes in the body of the JWT token.

Authentication examples

The following examples show how to authenticate by using each grant type.

Authorization Code Grant

Request URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20spring_read%20spring_write&client_id=5c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://localhost/

Implicit Grant

Request URL:

https://account-d.docusign.com/oauth/auth?response_type=token&scope=spring_read%20spring_write%20signature&client_id=5c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://localhost/

JSON Web Token (JWT) Grant

Request URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=impersonation%20content&client_id=5c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://localhost/

JSON request body:

{
  "iss": "6c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f", "iat": 1541785491,
  "exp": 1561785491,
  "aud": "account-d.docusign.com",
  "scope": "signature content"
}

Next steps