Skip to main content

​
API Key Authentication

Documind uses API key authentication. Every request to the API must include a valid API key in the X-API-Key header. 
X-API-Key: YOUR_API_KEY

​
Creating API Keys

1

Navigate to API Keys

Access the API Keys section in your dashboard at /api-keys.
2

Create New Key

Click “Create API Key” and provide:
  • Name: Descriptive name for the key (e.g., “Production Automation”)
  • Description: Optional details about key usage
  • Scopes: Permissions for the key (read/write access)
  • Expiration: Optional expiration date
The full API key is shown only once during creation. Store it securely.
3

Store Securely

Save the API key in a secure location:
  • Environment variables
  • Secrets management service (AWS Secrets Manager, Azure Key Vault)
  • Password manager
Never commit keys to version control or share them publicly.

​
Request Format

Include the API key in the X-API-Key header of every request: 
curl https://api.documind.com/api/v1/upload \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected]'

​
API Key Scopes

Control what operations each API key can perform:
ScopeDescriptionEndpoints
read_extractionsView extraction resultsGET /data/extractions, GET /pending-reviews
write_extractionsCreate and modify extractionsPOST /upload, POST /extract, PUT /review
read_api_keysList API keysGET /auth/api-keys
write_api_keysCreate/update API keysPOST /auth/api-keys, PUT /auth/api-keys/{id}
read_usageView usage metricsGET /usage/current, GET /usage/credits
adminFull access to all resourcesAll endpoints
For automation scripts, create keys with only the scopes they need: read_extractions and write_extractions.

​
Managing API Keys

​
List All Keys

curl https://api.documind.com/api/v1/auth/api-keys \
  -H 'X-API-Key: YOUR_API_KEY'

[
  {
    "id": "key_abc123",
    "name": "Production Bot",
    "prefix": "dk_live_",
    "scopes": ["read_extractions", "write_extractions"],
    "is_active": true,
    "is_revoked": false,
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-01-15T10:30:00Z"
  }
]

​
Update API Key

Update key properties like name, scopes, or expiration: 
curl -X PUT https://api.documind.com/api/v1/auth/api-keys/key_abc123 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Production Bot",
    "scopes": ["read_extractions", "write_extractions", "read_usage"],
    "expires_in_days": 365
  }'

​
Revoke API Key

Immediately disable an API key: 
curl -X DELETE https://api.documind.com/api/v1/auth/api-keys/key_abc123 \
  -H 'X-API-Key: YOUR_API_KEY'
Revoked keys cannot be reactivated. You must create a new key.

​
Organization-Wide Keys

Create API keys that work across your entire organization: 
{
  "name": "Org-wide Bot Key",
  "org_wide": true,
  "scopes": ["read_extractions", "write_extractions"],
  "expires_in_days": 90
}
Organization-wide keys:
  • Share credits across the organization
  • Access extractions from any team member
  • Ideal for shared automation infrastructure

​
Error Responses

​
401 Unauthorized

Missing or invalid API key: 
{
  "detail": "Invalid authentication credentials"
}
Solution: Verify your API key is correct and included in the Authorization header.

​
403 Forbidden

API key lacks required scope: 
{
  "detail": "Insufficient permissions for this operation"
}
Solution: Update the API key’s scopes or use a key with appropriate permissions.

​
402 Payment Required

Insufficient credits: 
{
  "detail": "Insufficient credits. Please upgrade your plan or wait for your daily credits to refresh."
}
Solution: Purchase more credits to continue processing.

​
Security Best Practices

Store API keys in environment variables, not in code:
.env
DOCUMIND_API_KEY=dk_live_abc123xyz

import os
api_key = os.environ['DOCUMIND_API_KEY']
Rotate API keys periodically (every 90 days recommended):
  1. Create a new API key
  2. Update your applications to use the new key
  3. Verify everything works
  4. Revoke the old key
Grant only the minimum scopes required:
  • Read-only automation: read_extractions only
  • Processing automation: read_extractions, write_extractions
  • Admin operations: All scopes
Track API key usage via the dashboard:
  • API calls per key
  • Last used timestamp
  • Unusual activity patterns

​
Next Steps

Quick Start Guide

Make your first authenticated API request