mirror of
https://github.com/documenso/documenso.git
synced 2026-07-26 01:45:08 +10:00
feat: docs v2 (#2460)
Co-authored-by: Catalin Pit <catalinpit@gmail.com>
This commit is contained in:
Lucas Smith
GitHub
@@ -0,0 +1,202 @@
|
||||
---
|
||||
title: Authentication
|
||||
description: Generate an API key and authenticate your requests.
|
||||
---
|
||||
|
||||
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Documenso account (cloud or self-hosted)
|
||||
- A Documenso account on any plan (Free, Individual, Team, or Enterprise)
|
||||
|
||||
<Callout type="info">
|
||||
Free accounts include API access with a limit of 5 documents per month. [Upgrade to a paid
|
||||
plan](https://documen.so/pricing) for higher limits.
|
||||
</Callout>
|
||||
|
||||
## Create an API Token
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
### Open settings
|
||||
|
||||
- Log in to your Documenso account
|
||||
- Click your avatar in the top right corner
|
||||
- Select **Settings** from the dropdown menu
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Navigate to the API Tokens tab
|
||||
|
||||
Go to **Settings** and open the **API Tokens** tab.
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 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**
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Copy your token
|
||||
|
||||
Your token is displayed once after creation. Copy it immediately and store it securely.
|
||||
|
||||
|
||||
|
||||
<Callout type="warn">
|
||||
You cannot view the token again after leaving this page. If you lose it, you must create a new
|
||||
token.
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Using Your Token
|
||||
|
||||
Include the token in the `Authorization` header of your HTTP requests.
|
||||
|
||||
### cURL
|
||||
|
||||
```bash
|
||||
curl https://app.documenso.com/api/v2/documents \
|
||||
-H "Authorization: api_xxxxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
### JavaScript / TypeScript
|
||||
|
||||
```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:
|
||||
|
||||
```typescript
|
||||
import { Documenso } from '@documenso/sdk-typescript';
|
||||
|
||||
const client = new Documenso({
|
||||
apiKey: 'api_xxxxxxxxxxxxxxxx',
|
||||
});
|
||||
|
||||
const documents = await client.documents.find();
|
||||
```
|
||||
|
||||
SDKs are available for [TypeScript](https://github.com/documenso/sdk-typescript), [Python](https://github.com/documenso/sdk-python), and [Go](https://github.com/documenso/sdk-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` |
|
||||
|
||||
<Callout type="info">
|
||||
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](https://app.documenso.com/api/v1/openapi).
|
||||
</Callout>
|
||||
|
||||
<Callout type="info">
|
||||
The API is available on all plans, including Free (5 documents per month). [Fair
|
||||
Use](/docs/policies/fair-use) applies to all API usage.
|
||||
</Callout>
|
||||
|
||||
## 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-prod` or `backend-staging` help 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:
|
||||
|
||||
```bash
|
||||
# .env (do not commit this file)
|
||||
DOCUMENSO_API_KEY=api_xxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
```typescript
|
||||
const 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:
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Steps>
|
||||
<Step>
|
||||
Go to **Settings** > **API Tokens**
|
||||
</Step>
|
||||
<Step>
|
||||
Find the token you want to revoke
|
||||
</Step>
|
||||
<Step>
|
||||
Click the delete icon next to the token
|
||||
</Step>
|
||||
<Step>
|
||||
Confirm the deletion
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Revoked tokens stop working immediately. Any integrations using that token will receive `401 Unauthorized` errors.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordions type="multiple">
|
||||
<Accordion title="401 Unauthorized — Missing or invalid token">
|
||||
Check that you included the token in the `Authorization` header.
|
||||
</Accordion>
|
||||
<Accordion title="401 Unauthorized — Expired token">Create a new token in settings.</Accordion>
|
||||
<Accordion title="403 Forbidden — Token doesn't have access to the resource">
|
||||
Ensure you're accessing resources owned by the token's account.
|
||||
</Accordion>
|
||||
</Accordions>
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Make your first API call](/docs/developers/getting-started/first-api-call) - Create a document via the API
|
||||
- [API Reference](/docs/developers/api) - Explore available endpoints
|
||||
Reference in New Issue
Block a user