Authentication

The Doclo API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Authorization Header

Authorization: Bearer dc_live_your_api_key

Example request:

curl https://app.doclo.ai/api/v1/flows \
  -H "Authorization: Bearer dc_live_your_api_key"

API Key Format

API keys have a prefix indicating their environment:

Prefix	Environment	Description
`dc_live_`	Production	Real document processing, uses credits
`dc_test_`	Test	For development, limited functionality

Get your API keys from the Doclo Dashboard.

Scopes

API keys are assigned scopes that control access to specific endpoints:

Scope	Endpoints	Description
`flows:read`	GET /flows, GET /flows/	List and view flow definitions
`flows:execute`	POST /flows//run	Execute flows
`executions:read`	GET /runs/	View execution status and results
`executions:cancel`	POST /runs//cancel	Cancel running executions

A typical integration key includes all scopes:

flows:read, flows:execute, executions:read, executions:cancel

For read-only access (e.g., dashboards), create a key with only:

flows:read, executions:read

Authentication Errors

Missing Authorization Header

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing authorization header"
  }
}

Status: 401 Unauthorized Fix: Add the Authorization: Bearer <api_key> header to your request.

Invalid API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Status: 401 Unauthorized Fix: Verify your API key is correct and hasn’t been revoked.

Insufficient Scope

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope: flows:execute"
  }
}

Status: 403 Forbidden Fix: Generate a new API key with the required scopes.

Security Best Practices

Never expose API keys in client-side code, public repositories, or browser applications. API keys should only be used in server-side code.

Environment Variables

Store API keys in environment variables:

# .env (never commit this file)
DOCLO_API_KEY=dc_live_your_api_key

const apiKey = process.env.DOCLO_API_KEY;

Key Rotation

Rotate API keys regularly:

Generate a new key in the Dashboard
Update your application to use the new key
Verify the new key works
Revoke the old key

Separate Keys Per Environment

Use different API keys for:

Development (dc_test_ keys)
Staging (production keys with limited scope)
Production (full access keys)

Monitor Usage

Review API usage in the Dashboard to detect:

Unexpected spikes in requests
Requests from unknown IP addresses
Failed authentication attempts

Rate Limits by Key Type

Key Type	Requests/minute	Concurrent executions
Test	60	2
Live (Free)	100	5
Live (Pro)	1000	50
Live (Enterprise)	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699574400

Overview

Flows

Runs

Authentication

Authorization Header

API Key Format

Scopes

Authentication Errors

Missing Authorization Header

Invalid API Key

Insufficient Scope

Security Best Practices

Environment Variables

Key Rotation

Separate Keys Per Environment

Monitor Usage

Rate Limits by Key Type

Next Steps

Errors

Run Flow

​Authorization Header

​API Key Format

​Scopes

​Authentication Errors

​Missing Authorization Header

​Invalid API Key

​Insufficient Scope

​Security Best Practices

​Environment Variables

​Key Rotation

​Separate Keys Per Environment

​Monitor Usage

​Rate Limits by Key Type

​Next Steps

Errors

Run Flow

Authorization Header

API Key Format

Scopes

Authentication Errors

Missing Authorization Header

Invalid API Key

Insufficient Scope

Security Best Practices

Environment Variables

Key Rotation

Separate Keys Per Environment

Monitor Usage

Rate Limits by Key Type

Next Steps