DocuSign API Authentication: Methods, Setup, and Best Practices

Authentication overview

DocuSign API provides methods for applications to securely identify themselves and authorize access to user resources, such as sending documents for signature or retrieving envelope statuses. The primary authentication mechanism is OAuth 2.0, which is an industry-standard protocol designed for delegated authorization. This protocol allows applications to obtain limited access to user accounts on an HTTP service, such as DocuSign, without sharing user credentials. DocuSign API supports specific OAuth 2.0 flows tailored for different application types and use cases.

For scenarios requiring user interaction, the DocuSign API offers the Authorization Code Grant flow. This method is suitable for web applications where users can be redirected to a DocuSign login page to grant consent. Upon successful authentication and user consent, DocuSign redirects the user back to the application with an authorization code, which can then be exchanged for an access token and refresh token. Access tokens are short-lived credentials used to make API calls, while refresh tokens allow applications to obtain new access tokens without requiring the user to re-authenticate.

For server-to-server integrations or scenarios where user interaction is not feasible, DocuSign supports the JSON Web Token (JWT) Grant flow. This method enables an application to authenticate on behalf of a user using a private key and a pre-configured integration key (client ID). JWT authentication is often preferred for daemon applications, automated workflows, or when integrating with internal systems where user presence during authentication is not required. The JWT flow relies on digital signatures to ensure the integrity and authenticity of the token, providing a robust security mechanism.

Additionally, DocuSign API maintains support for a Legacy Header Authentication method, which involves passing a username and password directly in the request headers. While still functional for existing integrations, DocuSign recommends migrating to OAuth 2.0 for new development due to its enhanced security features and compliance with modern authentication standards. OAuth 2.0 minimizes the exposure of user credentials and provides better mechanisms for token revocation and scope management.

Supported authentication methods

DocuSign API supports several authentication methods to accommodate various integration architectures and security requirements. The choice of method depends on factors such as user interaction, application type, and the desired level of automation.

Getting your credentials

To begin authenticating with the DocuSign API, you need to obtain the necessary credentials. The process typically starts in the DocuSign Developer Sandbox, which provides a non-production environment for testing and development.

1. Create a Developer Account: If you don't already have one, sign up for a free developer account on the DocuSign Developer Center. This will give you access to the Sandbox environment.
2. Create an Integration Key (Client ID): Inside your developer account, navigate to "Apps and Keys." Here, you will create a new integration key (also known as a client ID). This key identifies your application to DocuSign. During this process, you will also specify redirect URIs for OAuth 2.0 Authorization Code Grant and generate a client secret if your application is confidential.
3. Generate RSA Key Pair (for JWT Grant): If you plan to use the OAuth 2.0 JWT Grant flow, you will need to generate an RSA key pair. The private key will be used by your application to sign the JWT, and the public key needs to be uploaded to your DocuSign integration key settings. DocuSign provides tools and instructions within the developer environment for generating and managing these keys.
4. Obtain User IDs/Account IDs: For API calls, you will often need the User ID of the user on whose behalf you are acting and the Account ID of the DocuSign account. These can be found in your DocuSign account settings or retrieved programmatically via API calls after initial authentication.
5. Go-Live Process: Once your integration is fully tested in the Sandbox, you will need to complete a Go-Live review process to move your integration to the production environment. This typically involves a review by DocuSign to ensure adherence to best practices and API usage policies. Production credentials will be issued upon successful completion.

Authenticated request example

Here's an example of how to make an authenticated request using an OAuth 2.0 Authorization Code Grant access token to retrieve a list of envelopes. This example assumes you have already completed the Authorization Code Grant flow and obtained a valid access token.

Example: Get Envelopes with OAuth 2.0 (Authorization Code Grant)

First, obtain an access token. This involves redirecting the user, handling the callback, and exchanging the authorization code for an access token. The DocuSign Authorization Code Grant guide provides detailed steps for this process.

GET /restapi/v2.1/accounts/{accountId}/envelopes?from_date=2024-01-01 HTTP/1.1
Host: demo.docusign.net
Authorization: Bearer YOUR_ACCESS_TOKEN
X-DocuSign-Agent: MyDocuSignApp/1.0
Accept: application/json

{
  "startPosition": "0",
  "endPosition": "0",
  "resultSetSize": "0",
  "totalSetSize": "1",
  "nextUri": "",
  "previousUri": "",
  "envelopes": [
    {
      "status": "completed",
      "documentsUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/documents",
      "recipientsUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/recipients",
      "attachmentsUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/attachments",
      "envelopeUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "envelopeId": "a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "customFieldsUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/custom_fields",
      "notificationUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/notification",
      "statusChangedDateTime": "2024-05-29T10:00:00.0000000Z",
      "documentsCombinedUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/documents/combined",
      "certificateUri": "/envelopes/a843b016-xxxx-xxxx-xxxx-xxxxxxxxxxxx/documents/certificate"
    }
  ]
}

In this example:

• {accountId} should be replaced with the actual Account ID of the DocuSign account.
• YOUR_ACCESS_TOKEN is the OAuth 2.0 access token obtained after a successful authentication flow.
• The Host header points to the appropriate DocuSign environment (demo.docusign.net for Sandbox, www.docusign.net for production).
• The X-DocuSign-Agent header is a recommended practice to identify your application for logging and debugging purposes.

For more detailed examples and SDK-specific implementations, refer to the DocuSign eSignature REST API reference.

Security best practices

Implementing robust security measures is crucial when integrating with the DocuSign API to protect sensitive document data and user accounts. Adhering to these best practices helps mitigate risks and ensures compliance.

• Use OAuth 2.0: Always prioritize OAuth 2.0 (Authorization Code Grant or JWT Grant) over Legacy Header Authentication for new integrations. OAuth 2.0 is designed for secure delegated access, minimizing direct exposure of user credentials. Refer to the OAuth 2.0 security best current practice for general guidance.
• Secure Client Secrets: If using Authorization Code Grant, keep your client secret confidential. Store it securely in environment variables or a secrets management service, not directly in source code. Rotate client secrets regularly.
• Protect Private Keys (JWT): For JWT Grant, safeguard your private RSA key. It should never be exposed publicly or committed to version control. Implement strict access controls for systems accessing this key.
• Implement TLS/SSL: Ensure all communication with the DocuSign API is encrypted using Transport Layer Security (TLS 1.2 or higher). DocuSign enforces HTTPS for all API endpoints, but it's essential to verify your application's configuration.
• Validate Redirect URIs: For Authorization Code Grant, meticulously configure and validate your redirect URIs. Only allow whitelisted URIs to prevent redirection attacks.
• Implement State Parameter (OAuth 2.0): When using the Authorization Code Grant, always include a unique, unguessable state parameter in the authorization request. Validate this parameter in the callback to prevent Cross-Site Request Forgery (CSRF) attacks.
• Handle Tokens Securely:
  • Access Tokens: Store access tokens in memory for their short lifespan. Avoid persisting them to disk.
  • Refresh Tokens: If your application requires long-term access, store refresh tokens securely (e.g., encrypted in a database). Treat them as highly sensitive credentials. Implement refresh token rotation if supported.
  • Token Expiration: Always check for token expiration and gracefully handle token refresh.
• Least Privilege Principle: Request only the necessary scopes (permissions) for your integration. Granting excessive permissions increases the attack surface.
• Error Handling and Logging: Implement robust error handling for authentication failures and log relevant events (e.g., failed login attempts, token refresh failures) for monitoring and auditing. Avoid logging sensitive information like raw credentials or tokens.
• Regular Audits and Updates: Periodically review your authentication implementation and stay updated with DocuSign's latest security recommendations and API changes. Regularly audit access logs for suspicious activity.