Authentication

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

Navigate to API Keys

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

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.

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.cloud/api/v1/upload \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@document.pdf'

import requests

headers = {
    'X-API-Key': API_KEY
}

response = requests.post(
    'https://api.documind.cloud/api/v1/upload',
    headers=headers,
    files={'files': open('document.pdf', 'rb')}
)

const response = await fetch('https://api.documind.cloud/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY
  },
  body: formData
});

API Key Scopes

Control what operations each API key can perform:

Scope	Description	Endpoints
`extractions:read`	View extraction results	`GET /data/extractions`, `GET /pending-reviews`
`extractions:write`	Create and modify extractions	`POST /upload`, `POST /extract`, `PUT /review`
`api_keys:read`	List API keys	`GET /auth/api-keys`
`api_keys:write`	Create/update API keys	`POST /auth/api-keys`, `PUT /auth/api-keys/{id}`
`usage:read`	View usage metrics	`GET /usage/current`, `GET /usage/credits`
`admin`	Full access to all resources	All endpoints

For automation scripts, create keys with only the scopes they need: extractions:read and extractions:write.

Managing API Keys

List All Keys

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

[
  {
    "id": "key_abc123",
    "name": "Production Bot",
    "prefix": "dk_live_",
    "scopes": ["extractions:read", "extractions:write"],
    "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.cloud/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": ["extractions:read", "extractions:write", "usage:read"],
    "expires_in_days": 365
  }'

Revoke API Key

Immediately disable an API key:

curl -X DELETE https://api.documind.cloud/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": ["extractions:read", "extractions:write"],
  "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 X-API-Key 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

Environment Variables

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']

Key Rotation

Rotate API keys periodically (every 90 days recommended):

Create a new API key
Update your applications to use the new key
Verify everything works
Revoke the old key

Least Privilege

Grant only the minimum scopes required:

Read-only automation: extractions:read only
Processing automation: extractions:read, extractions:write
Admin operations: All scopes

Monitoring

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

Getting Started

Extraction Workflow

Review Workflow

Data Endpoints

Integration Patterns

API Key Authentication

Creating API Keys

Request Format

API Key Scopes

Managing API Keys

List All Keys

Update API Key

Revoke API Key

Organization-Wide Keys

Error Responses

401 Unauthorized

403 Forbidden

402 Payment Required

Security Best Practices

Next Steps

Quick Start Guide

​API Key Authentication

​Creating API Keys

​Request Format

​API Key Scopes

​Managing API Keys

​List All Keys

​Update API Key

​Revoke API Key

​Organization-Wide Keys

​Error Responses

​401 Unauthorized

​403 Forbidden

​402 Payment Required

​Security Best Practices

​Next Steps

Quick Start Guide

API Key Authentication

Creating API Keys

Request Format

API Key Scopes

Managing API Keys

List All Keys

Update API Key

Revoke API Key

Organization-Wide Keys

Error Responses

401 Unauthorized

403 Forbidden

402 Payment Required

Security Best Practices

Next Steps