Authentication overview

DocuSign utilizes OAuth 2.0 as its primary framework for authenticating applications accessing the eSignature REST API. This modern authorization standard allows client applications to obtain limited access to user accounts on an HTTP service, without exposing user credentials directly. OAuth 2.0 delegates user authentication to the service provider, enabling DocuSign to manage user identities and consent while applications receive secure access tokens.

The authentication process typically involves an application requesting authorization from a user, who then grants or denies permission. Upon approval, DocuSign issues an access token to the application. This token is then included in subsequent API requests to authenticate the application and authorize its actions. This method is considered a best practice for API security, as detailed in the OAuth 2.0 specification, ensuring that sensitive user credentials are never handled by the integrating application itself.

DocuSign supports various OAuth 2.0 grant types to accommodate different application architectures and use cases, from server-side web applications to client-side single-page applications and mobile apps. Understanding the appropriate grant type for your application is crucial for implementing secure and functional integrations.

Supported authentication methods

DocuSign primarily supports OAuth 2.0 for API access, offering different grant types to suit various application scenarios. Each method is designed to balance security requirements with development convenience.

Method When to Use Security Level
Authorization Code Grant Server-side web applications, where client secret can be securely stored. Ideal for applications that need persistent access or high security. High: Securely exchanges an authorization code for an access token, preventing direct token exposure in the browser.
Implicit Grant (Deprecated for new integrations) Client-side applications (e.g., single-page apps), where a server cannot securely store a client secret. Tokens are returned directly to the client. Medium: Tokens are exposed in the browser's URL fragment, making it less secure than Authorization Code Grant for new applications. DocuSign recommends Authorization Code Grant with PKCE.
JSON Web Token (JWT) Grant Server-to-server integrations without direct user interaction, or when impersonating a user for specific actions. Requires pre-authorization by an administrator. High: Uses an RSA private key to sign a JWT, providing strong cryptographic assurance of the client's identity.
Password Grant (Resource Owner Password Credentials) Highly trusted first-party applications where the user directly provides credentials to the client. Not recommended for third-party applications. Medium: Requires the client to handle user credentials, increasing risk. Generally discouraged in favor of other grants.

For most new integrations, particularly those involving web applications, the Authorization Code Grant is recommended due to its robust security model. For server-to-server integrations where user interaction is not feasible, the JWT Grant provides a secure alternative.

Getting your credentials

To begin authenticating with DocuSign, you need to set up an application in the DocuSign developer environment and obtain the necessary credentials. This process typically involves creating an integration key and configuring its settings.

  1. Create a Developer Account: If you don't already have one, sign up for a DocuSign Developer Account. This provides access to a sandbox environment for testing your integrations without affecting live data.
  2. Create an Integration Key: Navigate to the Apps and Keys section within your developer account. Here, you will create a new Integration Key (also known as a Client ID). This key uniquely identifies your application to DocuSign.
  3. Generate Client Secret (for Authorization Code Grant): For grant types like Authorization Code, you will need to generate a Client Secret associated with your Integration Key. This secret is a highly sensitive credential that your application uses to authenticate itself when exchanging an authorization code for an access token.
  4. Configure Redirect URIs: Specify the Redirect URIs (Callback URLs) for your application. These are the URLs to which DocuSign will redirect the user's browser after they have granted or denied consent to your application. These must be exact matches to what DocuSign expects.
  5. Generate RSA Key Pair (for JWT Grant): If you plan to use the JWT Grant, you will need to generate an RSA key pair. The public key is uploaded to your DocuSign integration key settings, and your application uses the corresponding private key to sign JSON Web Tokens. DocuSign's JWT Grant guide provides detailed instructions on this process.

It is critical to store your Client Secret and RSA Private Key securely. They should never be exposed in client-side code, public repositories, or transmitted over insecure channels. DocuSign provides comprehensive developer guides that walk through credential setup for various authentication flows.

Authenticated request example

Once you have obtained an access token using one of the OAuth 2.0 grant types, you can include it in your API requests to DocuSign. The access token is typically sent in the Authorization header of your HTTP request, using the Bearer scheme.

Here's a conceptual example using a Python SDK (DocuSign provides SDKs for multiple languages) to list envelopes, assuming an access token has already been acquired:

from docusign_esign import ApiClient, EnvelopesApi
from docusign_esign.client.api_exception import ApiException

# Assume accessToken is obtained via OAuth 2.0 flow
access_token = "YOUR_ACCESS_TOKEN"
account_id = "YOUR_ACCOUNT_ID" # Obtained during OAuth login or from user info endpoint
base_path = "https://demo.docusign.net/restapi" # Use demo for sandbox, production for live

api_client = ApiClient()
api_client.host = base_path
api_client.set_default_header("Authorization", f"Bearer {access_token}")

envelopes_api = EnvelopesApi(api_client)

try:
    # Call the Envelopes API to list envelopes
    options = envelopes_api.list_status_changes_options()
    options.from_date = "2023-01-01"
    
    response = envelopes_api.list_status_changes(account_id, options_for_api=options)
    print("Envelopes retrieved:")
    for envelope in response.envelopes:
        print(f"  Envelope ID: {envelope.envelope_id}, Status: {envelope.status}")

except ApiException as e:
    print(f"Error calling DocuSign API: {e}")

This example demonstrates how the access_token is used to authorize the request to the DocuSign API. The account_id identifies the specific DocuSign account on which the actions are performed. Always ensure you are using the correct base_path for your environment (demo for testing, production for live operations).

Security best practices

Implementing DocuSign authentication securely is paramount to protect sensitive document workflows and user data. Adhering to these best practices will help mitigate common security risks:

  • Use OAuth 2.0 Authorization Code Grant with PKCE: For web and mobile applications, the Authorization Code Grant with Proof Key for Code Exchange (PKCE) is the most secure method. PKCE adds an additional layer of security by mitigating authorization code interception attacks, especially relevant for public clients that cannot securely store a client secret. The IETF RFC 7636 details the PKCE specification.
  • Securely Store Client Secrets and Private Keys: Never embed client secrets directly in client-side code, mobile applications, or public repositories. Store them in secure server-side environments, environment variables, or dedicated secret management services. For JWT grants, protect your RSA private key with the highest level of security, as its compromise would allow unauthorized token generation.
  • Validate Redirect URIs: Always register specific, fully qualified Redirect URIs in your DocuSign integration key settings. Implement strict validation on your server to ensure that the redirect_uri parameter in the authorization request matches one of your registered URIs exactly. This prevents open redirect vulnerabilities.
  • Refresh Tokens Securely: When using refresh tokens to obtain new access tokens without re-authenticating the user, store them securely and treat them with the same care as client secrets. Refresh tokens should be encrypted at rest and transmitted only over HTTPS.
  • Implement Error Handling and Logging: Robust error handling should prevent sensitive information from being exposed in error messages. Log authentication failures and suspicious activity for monitoring and auditing purposes.
  • Scope Management: Request only the minimum necessary scopes (permissions) for your application to function. Over-privileged tokens increase the blast radius in case of compromise. DocuSign API scopes are detailed in the API Reference documentation.
  • Regularly Rotate Credentials: Periodically rotate client secrets and RSA key pairs to minimize the impact of a potential compromise. Establish a clear process for credential rotation.
  • Use HTTPS Everywhere: Ensure all communication with the DocuSign API and between your application components uses HTTPS to encrypt data in transit and prevent eavesdropping.
  • Monitor for API Usage Abnormalities: Implement monitoring to detect unusual patterns in API usage that could indicate a security breach, such as a sudden spike in requests or access from unexpected locations.

By following these guidelines, developers can build secure and resilient integrations with DocuSign, protecting both their applications and their users' data.