DocuSign Getting Started: Setup, Keys, and First API Call (2026)

Getting started overview

Integrating with DocuSign's eSignature API involves a sequence of steps designed to ensure secure and functional access to document signing capabilities. The process begins with establishing a developer account, which provides access to a sandbox environment for testing. Following account creation, developers register an application to obtain the necessary credentials for authentication. DocuSign primarily uses OAuth 2.0 for secure authorization, requiring an understanding of its flow for token management. Once authenticated, developers can make API calls to perform actions such as creating envelopes, adding documents and recipients, and sending them for signature. DocuSign provides comprehensive eSignature REST API documentation and SDKs in multiple programming languages to facilitate this integration.

This guide outlines the foundational steps:

1. Account Creation: Set up a free developer account.
2. Application Registration: Register your application to obtain client credentials.
3. Authentication Setup: Configure OAuth 2.0 to get an access token.
4. First API Call: Send a simple document for signature.

Create an account and get keys

To begin development with DocuSign, you must create a developer account. This account grants you access to the DocuSign demo environment, where you can test your integrations without affecting live production data or incurring charges. The demo environment is isolated from the production environment, allowing for safe experimentation.

1. Sign up for a Developer Account

Navigate to the DocuSign Developer Center and complete the registration for a free developer account. This process typically requires an email address and basic contact information. Upon successful registration, you will receive an activation email to confirm your account.

2. Register Your Application

After activating your account, log in to the DocuSign demo environment. From the dashboard, you will need to register a new application. This step generates the essential credentials required for your application to interact with the DocuSign API.

• Go to Settings > Apps and Keys.
• Click ADD APP AND INTEGRATION KEY.
• Provide a descriptive name for your application.
• Upon creation, DocuSign will provide an Integration Key (also known as Client ID). This key uniquely identifies your application.
• You will also need to generate a Secret Key (Client Secret) for your application. This key should be kept confidential and used for server-side authentication flows.
• Configure Redirect URIs. These are the URLs where DocuSign will send the user's browser after successful authentication. For testing and development, you might use http://localhost:8080/callback or a similar local endpoint.

The Integration Key and Secret Key are your primary API credentials. The Integration Key identifies your application, while the Secret Key authenticates your application to DocuSign's OAuth 2.0 servers. Keep both secure and do not expose them in client-side code.

3. Obtain Your Account Base URI

The base URI is the specific endpoint for your DocuSign account in the demo environment. It is essential for constructing API requests. You can find your base URI in the Apps and Keys section under your user profile, typically listed as Account's Base URI or similar. It usually follows the pattern https://demo.docusign.net/restapi/v2.1/accounts/{account_id}.

Your first request

Making your first request involves obtaining an OAuth 2.0 access token and then using it to send an envelope. DocuSign supports several OAuth 2.0 flows, with the Authorization Code Grant being common for web applications and JWT Grant for server-to-server integrations. For a quick start, we will outline the Authorization Code Grant flow, which involves user consent.

1. Configure OAuth 2.0 Consent

Before your application can request an access token, a user (in the demo environment, this will be your developer user) must grant consent for your application to act on their behalf. This is a one-time process for each user and application combination.

• Construct the consent URL using your Integration Key and a predefined scope (e.g., signature, extended).
• Open this URL in your browser, log in to your DocuSign developer account if prompted, and grant consent.
• For detailed steps on constructing the consent URL, refer to the DocuSign OAuth 2.0 Code Grant guide.

2. Get an Access Token

The Authorization Code Grant flow typically involves two steps: obtaining an authorization code and then exchanging it for an access token.

1. Redirect for Authorization Code: Redirect the user's browser to the DocuSign authorization endpoint. DocuSign will redirect back to your configured Redirect URI with an authorization code.
2. Exchange Code for Token: Your application's backend server makes a POST request to DocuSign's token endpoint, including the authorization code, your Integration Key, and Secret Key. DocuSign responds with an access token, which is a bearer token, along with a refresh token and token expiry details.

An access token is valid for a limited time (e.g., 8 hours). When it expires, you use the refresh token to obtain a new access token without requiring the user to re-authenticate. This process is crucial for maintaining continuous API access.

3. Send Your First Envelope (Example using cURL)

With an access token, you can now make your first API call. This example demonstrates sending a simple envelope with a single document and recipient. Replace {ACCESS_TOKEN}, {ACCOUNT_ID}, and {BASE_URI} with your actual values.

curl -X POST "{BASE_URI}/envelopes" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "emailSubject": "Please sign this document",
       "documents": [
         {
           "documentBase64": "JVBERi0xLjQNCiXn...", 
           "documentId": "1",
           "fileExtension": "pdf",
           "name": "Contract.pdf"
         }
       ],
       "recipients": {
         "signers": [
           {
             "email": "[email protected]",
             "name": "John Doe",
             "recipientId": "1",
             "routingOrder": "1",
             "tabs": {
               "signHereTabs": [
                 {
                   "documentId": "1",
                   "pageNumber": "1",
                   "xPosition": "100",
                   "yPosition": "100"
                 }
               ]
             }
           }
         ]
       },
       "status": "sent"
     }'

Note: documentBase64 should be the Base64 encoded content of your PDF document. The [email protected] should be an email address you can access to verify the signing process. The status: "sent" indicates that the envelope should be sent immediately after creation.

Quick Reference: DocuSign Getting Started Steps

Common next steps

After successfully sending your first envelope, consider these common next steps to enhance your DocuSign integration:

• Explore SDKs: DocuSign provides SDKs for C#, Java, Node.js, PHP, Python, and Ruby. Using an SDK can simplify API interactions by handling HTTP requests, JSON serialization, and authentication details.
• Implement Webhooks: Set up DocuSign Connect webhooks to receive real-time notifications about envelope status changes (e.g., signed, completed, declined). This eliminates the need for polling and provides a more efficient way to manage document workflows.
• Advanced Envelope Features: Explore more advanced features like template usage, custom fields, embedded signing, and bulk sending to automate complex agreement processes.
• Error Handling: Implement robust error handling in your application to gracefully manage API errors, network issues, and invalid input.
• Go Live: When your application is ready, follow DocuSign's Go-Live process to move your integration from the demo environment to production. This involves a review process to ensure your application meets DocuSign's integration standards.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check Credentials: Double-check your Integration Key (Client ID) and Secret Key for typos. Ensure they are correctly passed in your OAuth 2.0 token request.
• Verify Access Token: Confirm that your access token is valid and not expired. If expired, use your refresh token to obtain a new one. Ensure the access token is correctly included in the Authorization: Bearer {ACCESS_TOKEN} header.
• Base URI: Ensure you are using the correct base URI for your demo account. Mixing demo and production URIs will result in authentication failures.
• Redirect URI Mismatch: If using the Authorization Code Grant, ensure the Redirect URI configured in your DocuSign app matches the one used in your authorization request exactly.
• Scopes: Verify that the scopes requested during OAuth consent (e.g., signature, extended) are appropriate for the API calls you are making. Insufficient scopes can lead to permission errors.
• JSON Payload: Review your JSON request body for syntax errors, missing required fields, or incorrect data types. Use a JSON validator if unsure. The documentBase64 content must be a valid Base64 encoded string of a PDF document.
• Network Issues: Check your network connectivity. If you are behind a firewall, ensure that your application can reach DocuSign's API endpoints.
• DocuSign Developer Logs: The DocuSign demo account provides API request logs under Settings > API Logs. These logs can offer detailed error messages from the DocuSign server, which are invaluable for debugging.
• Error Messages: Pay close attention to the error messages returned in the API response. DocuSign's API errors are often descriptive and point to the root cause of the problem.

For persistent issues, consult the DocuSign API Request Logging documentation or reach out to the DocuSign developer community or support channels.