API Tokens

Create and manage API tokens for authenticating your requests

API tokens allow you to authenticate requests to the Documenso API. Create, manage, and revoke tokens through the Documenso dashboard.

Creating an API Token

1. Navigate to API Tokens

   Sign in to your Documenso account and navigate to:

   Settings → API Tokens

   Or for team tokens:

   Team Settings → API Tokens

   You must be a team admin to create team API tokens.

2. Create New Token

   Click the Create Token button and provide:

   • Token Name: A descriptive name to identify the token (minimum 3 characters)
   • Expiration: Optional expiration date for security

   Choose a descriptive name like production-api, staging-integration, or zapier-webhook to easily identify tokens later.

3. Copy Your Token

   After creation, your token will be displayed once. Copy it immediately and store it securely.

   This is your only chance to copy the token. It cannot be retrieved later. If you lose it, you’ll need to create a new token.

   The token format will be:

   api_<16-character-alphanumeric-id>
   
4. Store Securely

   Store your API token in a secure location:

   • Environment variables in your application
   • Secret managers like AWS Secrets Manager, HashiCorp Vault
   • CI/CD secrets for automated workflows

   Never commit tokens to version control or expose them in client-side code.

Token Creation Implementation

The token generation process uses a secure alphanumeric ID generator:

Source: packages/lib/server-only/public-api/create-api-token.ts

import { alphaid } from '../../universal/id';
import { hashString } from '../auth/hash';

export const createApiToken = async ({
  userId,
  teamId,
  tokenName,
  expiresIn,
}: CreateApiTokenInput) => {
  // Generate token with api_ prefix
  const apiToken = `api_${alphaid(16)}`;
  
  // Hash token for secure storage
  const hashedToken = hashString(apiToken);
  
  // Store hashed token in database
  const storedToken = await prisma.apiToken.create({
    data: {
      name: tokenName,
      token: hashedToken,
      expires: expiresIn ? DateTime.now().plus(timeConstantsRecords[expiresIn]).toJSDate() : null,
      userId,
      teamId,
    },
  });
  
  return {
    id: storedToken.id,
    token: apiToken, // Return plain token only once
  };
};

Expiration Options

When creating a token, you can optionally set an expiration date for enhanced security:

No Expiration

Token remains valid indefinitely until manually deleted.

Best for:

• Production integrations requiring long-term stability
• Service accounts with token rotation policies

1 Month

Token expires after 30 days.

Best for:

• Short-term projects
• Development and testing

3 Months

Token expires after 90 days.

Best for:

• Quarterly rotations
• Medium-term integrations

6 Months

Token expires after 180 days.

Best for:

• Semi-annual security reviews
• Standard production workflows

1 Year

Token expires after 365 days.

Best for:

• Annual security audits
• Long-term stable integrations

Set expiration dates as a security best practice. Implement token rotation before expiration to avoid service disruption.

Managing Tokens

View Existing Tokens

You can view all your API tokens in the settings page. For each token, you’ll see:

• Token Name: The descriptive name you provided
• Created Date: When the token was created
• Expiration Date: When the token expires (if set)
• Status: Active or expired

The actual token value is never displayed after creation - only metadata about the token.

Delete a Token

To revoke a token:

1. Navigate to Settings → API Tokens
2. Find the token you want to delete
3. Click Delete
4. Confirm the deletion

Deleting a token immediately revokes access. Any applications using this token will receive 401 Unauthorized errors.

Using Your Token

Once created, include your token in the Authorization header of all API requests:

cURL

curl https://app.documenso.com/api/v2/envelopes \
  -H "Authorization: Bearer api_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Environment Variable Setup

Store your API token as an environment variable for security:

.env

DOCUMENSO_API_TOKEN=api_your_token_here
DOCUMENSO_API_URL=https://app.documenso.com/api/v2

Token Security Best Practices

Never Expose Tokens

• Don’t commit tokens to version control (add .env to .gitignore)
• Don’t include tokens in client-side JavaScript
• Don’t log tokens in application logs
• Don’t share tokens in screenshots or documentation

Use Environment Variables

Store tokens in environment variables instead of hardcoding:

// Good
const apiToken = process.env.DOCUMENSO_API_TOKEN;

// Bad
const apiToken = 'api_a1b2c3d4e5f6g7h8';

Implement Token Rotation

Regularly rotate API tokens:

1. Create a new token
2. Update your application to use the new token
3. Verify the new token works
4. Delete the old token

Automate this process for production environments.

Use Separate Tokens Per Environment

Create different tokens for:

• Development
• Staging
• Production

This allows you to revoke environment-specific access without affecting others.

Monitor Token Usage

Regularly review your API tokens:

• Remove unused tokens
• Check for expired tokens
• Audit token access patterns
• Investigate unexpected usage spikes

Set Expiration Dates

Always set expiration dates for tokens when possible:

• Reduces risk from compromised tokens
• Forces regular security reviews
• Encourages token rotation practices

Troubleshooting

401 Unauthorized Error

Cause: Invalid or expired token

Solutions:

• Verify token is correctly copied (no extra spaces)
• Check if token has expired
• Ensure Bearer prefix is included if using that format
• Verify the user account is not disabled

Cannot Create Team Token

Cause: Insufficient permissions

Solution: You must be a team admin to create team API tokens. Contact your team admin to:

• Upgrade your role to admin, or
• Create the token on your behalf

Lost Token

Cause: Token not saved after creation

Solution: Tokens cannot be retrieved after creation. You must:

1. Delete the lost token
2. Create a new token
3. Update your application with the new token

Schema Reference

The API token creation request and response schemas:

Request Schema

export const ZCreateApiTokenRequestSchema = z.object({
  teamId: z.number(),
  tokenName: z.string().min(3, { 
    message: 'The token name should be 3 characters or longer' 
  }),
  expirationDate: z.string().nullable(),
});

Response Schema

export const ZCreateApiTokenResponseSchema = z.object({
  id: z.number(),
  token: z.string(), // Only returned once
});

Next Steps

Authentication

Learn how to use your token for API authentication

Rate Limits

Understand rate limits and how they affect your tokens