Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/documenso/documenso/llms.txt

Use this file to discover all available pages before exploring further.

Documenso uses API tokens to authenticate requests to the API. All API requests must include an Authorization header with a valid API token.

​
Authentication Method

The API uses Bearer token authentication. Include your API token in the Authorization header of every request: 
curl https://app.documenso.com/api/v2/envelopes \
  -H "Authorization: Bearer api_YOUR_TOKEN_HERE"

​
Token Format

API tokens follow this format: 
api_<16-character-alphanumeric-id>
Example: api_a1b2c3d4e5f6g7h8
API tokens are only shown once when created. Store them securely - they cannot be retrieved later.

​
Flexible Authorization Header

The API accepts the Authorization header in two formats: 
Authorization: Bearer api_YOUR_TOKEN_HERE
Both formats are supported, but the standard Bearer format is recommended for compatibility.

​
Token Storage and Security

API tokens are securely hashed using SHA-256 before storage. The implementation uses the following approach:
Source: packages/lib/server-only/public-api/get-api-token-by-token.ts
export const getApiTokenByToken = async ({ token }: { token: string }) => {
  const hashedToken = hashString(token);
  
  const apiToken = await prisma.apiToken.findFirst({
    where: {
      token: hashedToken,
    },
    // ... includes user and team data
  });
  
  if (!apiToken) {
    throw new AppError(AppErrorCode.UNAUTHORIZED, {
      message: 'Invalid token',
    });
  }
  
  if (apiToken.expires && apiToken.expires < new Date()) {
    throw new AppError(AppErrorCode.EXPIRED_CODE, {
      message: 'Expired token',
    });
  }
  
  return apiToken;
};
The raw token is never stored in the database - only the hashed version is persisted for security.

​
Token Validation

When you make an API request, the authentication middleware validates your token:
  1. Extracts token from the Authorization header
  2. Hashes the token using the same algorithm
  3. Looks up the hashed token in the database
  4. Validates expiration if an expiration date is set
  5. Checks user status to ensure the account is not disabled
  6. Attaches user and team context to the request

​
Authentication Errors

​
401 Unauthorized
error
Your API token is missing, invalid, or expired.
{
  "message": "API token was not provided"
}

​
Team vs. Personal Tokens

API tokens are associated with either a user or a team:
Team tokens allow you to create documents on behalf of the team. Actions are attributed to the team rather than an individual user.Use Cases:
  • Shared integrations across team members
  • Service accounts for automated workflows
  • Organization-wide document management
Requirements:
  • Must be a team admin to create team tokens
  • Token permissions match team capabilities

​
Testing Your Authentication

Verify your API token is working correctly: 
curl https://app.documenso.com/api/v1/me \
  -H "Authorization: Bearer api_YOUR_TOKEN_HERE"
A successful response confirms your token is valid and properly configured.

​
Next Steps

Create API Tokens

Learn how to create and manage your API tokens

Rate Limits

Understand rate limiting for authenticated requests

Build docs developers (and LLMs) love

Get started for freeTalk to us