How OAuth Works in Docusign Extension Apps

If you’re building a Docusign Extension App, OAuth is not optional. This guide bridges the gap between OAuth theory and practical implementation guidance.

By the end, you'll understand what OAuth actually means in this context, how Docusign uses it in Extension Apps, the difference between Authorization Code and Client Credentials flows, what your system is responsible for building, and how to handle common edge cases.

1. Getting Started with OAuth

OAuth is a mechanism for delegated access. Instead of sharing credentials directly, one system requests access, another system grants it via a token, and that token is used to make authorized requests going forward.

In the context of Docusign Extension Apps, the roles break down like this:

• Docusign acts as a client that wants to call your APIs

• Your Extension App acts as both:

  • Authorization server (issues tokens)

  • Resource server (validates tokens and serves requests)

The critical distinction: OAuth is not just authentication. It is a controlled way to grant access with defined scope and lifetime.

2. Where OAuth Fits in Extension Apps

Extension apps are invoked during Docusign workflows, and each invocation results in an HTTP request from Docusign to your API. Examples of these workflows include envelope creation, data validation, and external data fetches. OAuth is used to secure these system interactions.

Before Docusign can call your API, it must obtain and present a valid access token. This creates a hard boundary:

• No token → no access

• Invalid token → request rejected

• Expired token → re-authentication required

3. Process Overview

Here is the complete sequence for the Authorization Code flow:

1. User clicks Connect inside Docusign

2. Docusign redirects the browser to your /authorize endpoint

3. Your app authenticates the user and captures consent

4. Your app redirects back with code and state

5. Docusign calls your /token endpoint

6. Your app validates the request, authenticates the client, and exchanges the code for a token

7. Your app returns an access token (and optionally a refresh token)

Docusign calls your APIs with Authorization: Bearer <token>

4. OAuth Flows You Need to Know

4.1 Authorization Code Grant (User-Based Flow)

This is the primary flow for Extension Apps.Use it when you have multi-user environments, external customers, or any scenario requiring user identity.

Step-by-step breakdown

Step 1: Authorization request

Docusign redirects to: 

/authorize?client_id=...&redirect_uri=...&state=...

Step 2: User authentication and consent

Your app authenticates the user (via login, SSO, etc.) and determines what access is being granted.

Step 3: Authorization response

Your app redirects back:

redirect_uri?code=AUTH_CODE&state=STATE

The code is short-lived. The state must be preserved and validated.

Step 4: Token exchange

Docusign calls /token with the authorization code and client credentials.

Step 5: Token issuance

Your app returns:

// Sample token response from your /token endpoint
{
  "access_token": "abc123",
  "token_type": "Bearer",
  "expires_in": 3600
}

Optionally include refresh_token and scope. Include scope to specify the access your extension app needs, and include a refresh_token when available to help keep the connection active after the access token expires. This helps Docusign continue sending authorized requests without interrupting the workflow.

Key design considerations

• Authorization codes must be single-use

• Codes must expire quickly

• State must be validated

• Redirect URIs must be strictly validated

4.2 Client Credentials Grant (System-to-System Flow)

Used when no user context exists. Docusign calls /token directly with a client_id and client_secret. Your app validates the client identity and allowed scopes, then returns an access token.

This flow has no user login, no consent screen, and no browser redirects. Trust is based entirely on client authentication.

When to avoid this flow. Do not use Client Credentials when you need user-level auditing, when permissions vary per user, or when actions must be traceable to individuals.

4.3. Comparison of OAuth Flows

Authorization flows at a glance

In the Authorization Code Grant (ACG) flow, a user authenticates and provides consent to generate a short-lived authorization code. This code is then exchanged for an access token via a server-to-server call to the token endpoint, which must be authenticated using a secure client secret. This method is the required standard for all public extension apps to ensure that user identity is tracked and credentials remain protected.

Authorization Code Grant

The Client Credentials Grant allows private extension apps to exchange a client ID and secret for an access token. Designed for automated, server-to-server processes, this flow requires no user interaction and is intended for shared admin use within a single organization.

5. How Docusign Uses OAuth Internally

Docusign behaves as a well-defined OAuth client. It strictly follows the redirect → code → token pattern, stores tokens securely, and automatically attaches tokens to outbound requests.

From your app's perspective, you are responsible for implementing OAuth endpoints, enforcing security rules, and validating every incoming request. Docusign handles its side; your side must be airtight.

6. Required Endpoints

/authorize

Required only for Authorization Code flow. This endpoint must validate request parameters, authenticate the user, capture consent, generate an authorization code, and redirect back with that code and the original state value.

/token

This is the most critical endpoint in your implementation. It must:

• Validate the incoming grant request

• Authenticate the client

• Handle the grant type correctly (code exchange or client credentials)

• Enforce security checks: code validity, expiration, and reuse prevention

• Generate and return a properly formatted token response

// Correct token response format
{
  "access_token": "abc123",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use signed tokens (JWT is recommended). Include issuer, subject, expiration, and scopes in the payload.

Protected APIs

Every request from Docusign includes Authorization: Bearer <token>. On every protected request, validate the bearer token first. Only process the request if the token passes validation. Validation should include signature verification, expiry check, and scope validation.

7. Token Lifecycle

Tokens are not permanent, and this is an area many implementations get wrong. You must define:

• Expiry time: Define the access token lifetime, such as one hour. Use a duration that balances security and reliability. Shorter lifetimes reduce risk if a token is exposed, while longer lifetimes can reduce the frequency of token renewal.

• Refresh strategy: If supported, use refresh tokens to renew access without requiring the user to authorize again. Define when refresh should occur, how refresh failures are handled, and how refresh tokens are securely stored and protected.

• Revocation logic: Implement token revocation, especially for security-sensitive integrations. Revoke tokens when access is no longer needed, when a connection is removed, or when a token may have been compromised.

• If a token expires, Docusign must re-initiate the flow, and your system must reject the expired token outright.

8. Manifest Configuration

The manifest defines how Docusign connects to your OAuth implementation.

connections:
  - name: auth
    type: oauth2
    params:
      grantType: authorization_code
      customConfig:
        authorizationUrl: https://your-app/authorize
        tokenUrl: https://your-app/token

This tells Docusign where to redirect users for authorization and where to exchange tokens. Both URLs must be publicly accessible and correctly secured.

Common Pitfalls

Not validating state. The state value links the response to the original request, prevents request mismatch, and protects against CSRF-style attacks. Always validate it.

Weak token validation. Skipping signature or expiry checks creates serious security vulnerabilities. Validate every field, every time.

Reusable authorization codes. Authorization codes must be single-use and short-lived. A code that can be reused is a security hole.

Using Client Credentials when you need user context. This flow has no user, no consent, and no user-level audit trail. If any of those things matter to your integration, use Authorization Code instead.

Hardcoding secrets. Always use environment variables or a secure secrets vault. Never commit client_secret values to source control.

Final Mental Model

Three things to hold onto:

1. Docusign is the client. Your app is both the authorization server and the resource server.

2. OAuth defines how trust is established. Tokens carry that trust into every API call.

3. The core decision is simple: Do you need user identity, or just system-level access? That answer determines which flow you implement.

Once those three things click, implementation becomes structured and predictable. Everything else is wiring.

 FAQ

What OAuth flows does Docusign Extension Apps support? Extension Apps support two flows: Authorization Code Grant for user-based access, and Client Credentials Grant for system-to-system integrations where no user context is needed.

What endpoints do I need to build for a Docusign Extension App? For Authorization Code flow, you need /authorize and /token. For Client Credentials, only /token is required. All protected API routes also need bearer token validation logic.

Who acts as the OAuth server in an Extension App? Your app does. Docusign is the OAuth client — it requests tokens and presents them with API calls. Your app issues those tokens and validates them on every request.

What happens when an access token expires? Docusign must re-initiate the OAuth flow. Your app must reject expired tokens and not process any request that fails token validation.

Should I use Authorization Code or Client Credentials? Use Authorization Code when users are involved and you need identity, consent, or per-user permissions. Use Client Credentials for internal or backend service integrations where no user context exists.

How long should authorization codes be valid? Authorization codes should expire quickly — typically within 5 to 10 minutes. They must also be single-use; a code that has already been exchanged should be rejected immediately.

What format should my access tokens be in? JWT is recommended. Your tokens should include issuer, subject, expiration, and scopes in the payload, and must be signed so your app can verify them on every inbound request.

What is the state parameter and why does it matter? The state parameter links Docusign's authorization request to the response your app sends back. It prevents request mismatch and protects against CSRF-style attacks. Always generate it, pass it through, and validate it on return.