API Tokens

​

What are API Tokens?

​

Benefits of API Tokens

​

Automation

• Automatically create and send documents
• Integrate with your existing systems
• Build custom workflows
• Automate repetitive tasks

​

Integration

• Connect Documenso to other tools
• Sync data between systems
• Build custom applications
• Extend Documenso functionality

​

Security

• No need to share passwords
• Scoped to specific teams
• Can be revoked independently
• Expiration dates for added security

​

API Token Basics

​

Token Scope

• Each token belongs to a specific team
• Token has access to that team’s resources
• Can create documents, access templates, etc.
• Cannot access other teams’ data

​

Token Permissions

• Create documents: Upload and create new documents
• Send documents: Send documents to recipients
• Retrieve documents: Get document details and status
• Download documents: Download completed PDFs
• Manage recipients: Add and configure recipients
• Place fields: Add signature and form fields
• Access templates: Use team templates
• Webhooks: Configure webhooks (if admin)

​

Creating an API Token

​

Token Name

• Good: “Production Integration”, “GitHub Actions CI/CD”, “Analytics Dashboard”
• Bad: “Token 1”, “Test”, “API”

• Indicate the purpose or use case
• Include the integration or system name
• Mention environment (production, staging, dev)
• Date of creation if rotating regularly

​

Token Expiration

• 30 days: For testing and development
• 90 days: For production with regular rotation
• 1 year: For long-term integrations (rotate annually)
• No expiration: Only for trusted, long-term integrations (not recommended)

​

Storing Your Token

• Environment variables on your server
• Secure secret management services (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
• Password managers for small-scale use
• CI/CD platform secret stores (GitHub Secrets, GitLab CI Variables)

• ❌ Commit tokens to Git repositories
• ❌ Share tokens in chat or email
• ❌ Store in plain text files
• ❌ Include in frontend code

​

Using API Tokens

​

Authentication

Authorization: Bearer YOUR_TOKEN_HERE

curl -X GET \
  https://api.documenso.com/v1/documents \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE'

fetch('https://api.documenso.com/v1/documents', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json'
  }
})

​

API Documentation

• Visit the Documenso API Documentation
• Interactive API explorer
• Code examples in multiple languages
• Complete endpoint reference

​

Managing API Tokens

​

Viewing Tokens

1. Go to team settings
2. Navigate to API Tokens
3. View list of all tokens

• Token name
• Creation date
• Expiration date (if set)
• Last used date (coming soon)
• Created by (which team member)

​

Revoking Tokens

• Token was exposed or compromised
• Integration is no longer used
• Team member who created it left
• Replacing with a new token
• Regular security rotation

​

Token Rotation

• High-security environments: Every 30-90 days
• Standard environments: Every 6-12 months
• After security incidents: Immediately
• When team members leave: As soon as possible

​

Token Security Best Practices

​

Creation and Storage

• ✅ Create separate tokens for each integration
• ✅ Use descriptive names to track usage
• ✅ Set expiration dates when possible
• ✅ Store tokens in secure secret management systems
• ✅ Use environment variables, not hard-coded values

• ❌ Share tokens between multiple integrations
• ❌ Commit tokens to version control
• ❌ Store tokens in plain text
• ❌ Send tokens via email or chat
• ❌ Include tokens in client-side code

​

Usage

• ✅ Use HTTPS for all API requests
• ✅ Implement token refresh/rotation
• ✅ Monitor token usage and activity
• ✅ Limit token access to necessary systems
• ✅ Log API errors and failures

• ❌ Log tokens in application logs
• ❌ Include tokens in error messages
• ❌ Use tokens in URLs or query parameters
• ❌ Share tokens across environments (prod/dev/staging)

​

Management

• ✅ Regularly audit active tokens
• ✅ Revoke unused or old tokens
• ✅ Rotate tokens on a schedule
• ✅ Document what each token is used for
• ✅ Revoke immediately if compromised

• ❌ Keep unnecessary tokens active
• ❌ Use expired but not-yet-deleted tokens
• ❌ Grant token access to untrusted systems
• ❌ Ignore expiration notifications

​

Common Use Cases

​

Automated Document Generation

// Example: Create document from template
const response = await fetch('https://api.documenso.com/v1/templates/123/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipients: [
      { email: '[email protected]', name: 'John Doe', role: 'SIGNER' }
    ]
  })
});

​

Integration with CRM

// Example: Get document status
const response = await fetch(`https://api.documenso.com/v1/documents/${documentId}`, {
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`
  }
});

const document = await response.json();
// Update CRM with document.status

​

Bulk Document Sending

// Example: Bulk send from template
for (const recipient of recipients) {
  await fetch('https://api.documenso.com/v1/templates/123/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipients: [{ email: recipient.email, name: recipient.name, role: 'SIGNER' }]
    })
  });
}

​

Webhook Integration

1. Create API token
2. Set up webhook endpoint in team settings
3. Use webhook events to trigger actions
4. Use API token to fetch additional details when needed

​

Team Role Requirements

​

Creating Tokens

• ✅ Team Admin: Can create and manage all team tokens
• ❌ Team Manager: Cannot create tokens
• ❌ Team Member: Cannot create tokens

​

Viewing Tokens

• Team Admin: Can view and manage all tokens
• Team Manager: Can view tokens (may vary by implementation)
• Team Member: Cannot access token settings

​

Troubleshooting

​

Token Not Working

• Token expired
• Token was revoked
• Token not included in request
• Incorrect token format
• Insufficient permissions

• Check if token has expired
• Verify token hasn’t been deleted
• Ensure Authorization: Bearer TOKEN header is set
• Verify token string is complete (no extra spaces/characters)
• Confirm token belongs to the correct team

​

401 Unauthorized Error

• Invalid token
• Token doesn’t have access to requested resource
• Token belongs to different team

• Verify token is correct and active
• Check that you’re accessing resources from the token’s team
• Ensure token hasn’t been revoked
• Try creating a new token

​

403 Forbidden Error

• Token lacks necessary permissions
• Attempting admin-only operations
• Team doesn’t have access to feature

• Verify the operation is supported by API tokens
• Check team subscription and feature access
• Use admin credentials for admin operations

​

Token Creation Failed

• Not a team admin
• Team limit reached
• Invalid token parameters

• Verify you have Team Admin role
• Check if team has hit token limit
• Ensure token name is valid
• Try again or contact support

​

API Rate Limits

• Limits apply per token
• Vary by subscription plan
• Exceeded limits return 429 status
• Rate limit headers indicate remaining quota

• Implement rate limit handling
• Use exponential backoff for retries
• Cache responses when appropriate
• Monitor usage to stay within limits

​

Next Steps

• Read the API Documentation
• Set up webhooks for real-time updates
• Create templates for API usage
• Learn about automation workflows