Authentication

Doclo Cloud uses API keys for authentication. This guide covers key management, security best practices, and error handling.

API Key Format

Doclo API keys follow this format:

Prefix	Environment	Usage
`dc_live_`	Production	Real documents, billing enabled
`dc_test_`	Testing	Test data, no billing

Example: dc_live_org123_abcdefghijklmnopqrstuvwxyz123456

Getting API Keys

Log in to app.doclo.ai
Navigate to Settings → API Keys
Click Create API Key
Name your key (e.g., “Production Server”, “Development”)
Copy and securely store the key

API keys are shown only once. If you lose a key, you’ll need to create a new one.

Using API Keys

With the SDK

import { DocloClient } from '@doclo/client';

const client = new DocloClient({
  apiKey: process.env.DOCLO_API_KEY!
});

With REST API

Include the key in the Authorization header:

curl -X POST https://app.doclo.ai/api/v1/flows/flow_abc123/run \
  -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": {...}}'

Test vs Production Keys

Test Keys (`dc_test_`)

Safe for development and testing
Can connect to localhost and private IPs
No billing charges
Rate limits may be lower

Production Keys (`dc_live_`)

For production workloads
Cannot connect to localhost (SSRF protection)
Billing enabled
Full rate limits

// Check which mode the client is using
const client = new DocloClient({
  apiKey: process.env.DOCLO_API_KEY!
});

if (client.isTestMode) {
  console.log('Running with test key');
}

Key Security

Never expose API keys in client-side code, public repositories, or logs.

Do

Store keys in environment variables
Use secret management services (AWS Secrets Manager, Vault, etc.)
Rotate keys periodically
Use separate keys for different environments
Revoke unused keys

Don’t

Commit keys to version control
Log API keys
Share keys between applications
Use production keys in development

Environment Variables

# .env.local (development)
DOCLO_API_KEY=dc_test_...

# .env.production (production)
DOCLO_API_KEY=dc_live_...

// Load with dotenv
import 'dotenv/config';

const client = new DocloClient({
  apiKey: process.env.DOCLO_API_KEY!
});

Key Rotation

Rotate keys periodically to limit exposure:

Create a new API key
Update your application to use the new key
Deploy the update
Revoke the old key

Use separate keys for each deployment (staging, production) to rotate independently.

Rate Limits

API requests are rate limited per organization:

Plan	Requests/minute	Concurrent executions
Free	60	5
Pro	300	20
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705320000

Handling Rate Limits

import { DocloClient, RateLimitError } from '@doclo/client';

try {
  const result = await client.flows.run('flow_abc123', { ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    const retryAfter = error.rateLimitInfo?.retryAfter ?? 60;
    console.log(`Rate limited. Retry in ${retryAfter} seconds`);

    // Wait and retry
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    // Retry the request...
  }
}

Authentication Errors

Error Code	HTTP Status	Description
`INVALID_API_KEY`	401	Key format invalid or not found
`API_KEY_REVOKED`	401	Key has been revoked
`API_KEY_EXPIRED`	401	Key has expired
`INSUFFICIENT_SCOPE`	403	Key lacks required permissions

import {
  DocloClient,
  AuthenticationError,
  AuthorizationError
} from '@doclo/client';

try {
  const result = await client.flows.run('flow_abc123', { ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key
    console.error('Authentication failed:', error.code);
  } else if (error instanceof AuthorizationError) {
    // Valid key but insufficient permissions
    console.error('Authorization failed:', error.code);
  }
}

IP Allowlisting

For enhanced security, restrict API access to specific IP addresses:

Go to Settings → Security in the dashboard
Enable IP allowlisting
Add your server IP addresses

Requests from non-allowlisted IPs will be rejected with a 403 error.

Next Steps

Cloud Quickstart

Get started with Doclo Cloud

REST API Reference

Direct API documentation

Getting Started

Concepts

SDK

Doclo Cloud

Guides

Resources

Authentication

API Key Format

Getting API Keys

Using API Keys

With the SDK

With REST API

Test vs Production Keys

Test Keys (`dc_test_`)

Production Keys (`dc_live_`)

Key Security

Do

Don’t

Environment Variables

Key Rotation

Rate Limits

Handling Rate Limits

Authentication Errors

IP Allowlisting

Next Steps

Cloud Quickstart

REST API Reference

​API Key Format

​Getting API Keys

​Using API Keys

​With the SDK

​With REST API

​Test vs Production Keys

​Test Keys (dc_test_)

​Production Keys (dc_live_)

​Key Security

​Do

​Don’t

​Environment Variables

​Key Rotation

​Rate Limits

​Handling Rate Limits

​Authentication Errors

​IP Allowlisting

​Next Steps

Cloud Quickstart

REST API Reference

API Key Format

Getting API Keys

Using API Keys

With the SDK

With REST API

Test vs Production Keys

Test Keys (`dc_test_`)

Production Keys (`dc_live_`)

Key Security

Do

Don’t

Environment Variables

Key Rotation

Rate Limits

Handling Rate Limits

Authentication Errors

IP Allowlisting

Next Steps