Skip to main content
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:
PrefixEnvironmentUsage
dc_live_ProductionReal documents, billing enabled
dc_test_TestingTest data, no billing
Example: dc_live_org123_abcdefghijklmnopqrstuvwxyz123456

​
Getting API Keys

  1. Log in to app.doclo.ai
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Name your key (e.g., “Production Server”, “Development”)
  5. 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:
  1. Create a new API key
  2. Update your application to use the new key
  3. Deploy the update
  4. Revoke the old key
Use separate keys for each deployment (staging, production) to rotate independently.

​
Rate Limits

API requests are rate limited per organization:
PlanRequests/minuteConcurrent executions
Free605
Pro30020
EnterpriseCustomCustom
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 CodeHTTP StatusDescription
INVALID_API_KEY401Key format invalid or not found
API_KEY_REVOKED401Key has been revoked
API_KEY_EXPIRED401Key has expired
INSUFFICIENT_SCOPE403Key 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:
  1. Go to Settings → Security in the dashboard
  2. Enable IP allowlisting
  3. 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