Authentication
Generate an API key and authenticate your requests.
Prerequisites
- A Documenso account (cloud or self-hosted)
- A Documenso account on any plan (Free, Individual, Team, or Enterprise)
Free accounts include API access with a limit of 5 documents per month. Upgrade to a paid plan for higher limits.
Create an API Token
Open settings
- Log in to your Documenso account
- Click your avatar in the top right corner
- Select Settings from the dropdown menu
Generate a new token
- Click Create Token
- Enter a descriptive name (e.g.,
production-backend,zapier-integration) - Select an expiration period: never expires, 7 days, 1 month, 3 months, 6 months, or 1 year
- Click Create Token
Copy your token
Your token is displayed once after creation. Copy it immediately and store it securely.
You cannot view the token again after leaving this page. If you lose it, you must create a new token.
Using Your Token
Include the token in the Authorization header of your HTTP requests.
cURL
curl https://app.documenso.com/api/v2/documents \
-H "Authorization: api_xxxxxxxxxxxxxxxx"JavaScript / TypeScript
const response = await fetch('https://app.documenso.com/api/v2/documents', {
method: 'GET',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
},
});
const documents = await response.json();Using the TypeScript SDK
Documenso provides official SDKs that handle authentication for you:
import { Documenso } from '@documenso/sdk-typescript';
const client = new Documenso({
apiKey: 'api_xxxxxxxxxxxxxxxx',
});
const documents = await client.documents.find();SDKs are available for TypeScript, Python, and Go.
API Base URLs
| Environment | Base URL |
|---|---|
| Production | https://app.documenso.com/api/v2 |
| Staging | https://stg-app.documenso.com/api/v2 |
| Self-hosted | https://your-domain.com/api/v2 |
API V1 is deprecated. Use V2 for all new integrations. V1 only works with legacy documents created before the envelope system. If you need V1 documentation for migration purposes, see the V1 OpenAPI reference.
The API is available on all plans, including Free (5 documents per month). Fair Use applies to all API usage.
Token Security
API tokens grant full access to your account. Follow these practices to keep them secure:
- Never commit tokens to version control. Use environment variables instead.
- Use descriptive names. Names like
zapier-prodorbackend-staginghelp you identify token usage. - Set expiration dates. Shorter expiration periods reduce risk if a token is compromised.
- Rotate tokens regularly. Create new tokens and revoke old ones periodically.
- Use separate tokens per integration. If one is compromised, you only need to revoke that specific token.
- Revoke unused tokens. Delete tokens you no longer need from the API Tokens settings page.
Environment Variables
Store your token in an environment variable rather than hardcoding it:
# .env (do not commit this file)
DOCUMENSO_API_KEY=api_xxxxxxxxxxxxxxxxconst client = new Documenso({
apiKey: process.env.DOCUMENSO_API_KEY,
});Token Scope
API tokens have full access to your account, including:
- Creating, reading, updating, and deleting documents
- Managing recipients and fields
- Accessing templates
- Managing team resources (if the token owner has team access)
There is currently no way to create tokens with limited scopes or permissions.
Revoking a Token
To revoke a token:
Go to Settings > API Tokens
Find the token you want to revoke
Click the delete icon next to the token
Confirm the deletion
Revoked tokens stop working immediately. Any integrations using that token will receive 401 Unauthorized errors.
Troubleshooting
Next Steps
- Make your first API call - Create a document via the API
- API Reference - Explore available endpoints