Doclo Cloud uses API keys for authentication. This guide covers key management, security best practices, and error handling.
Doclo API keys follow this format:
| Prefix | Environment | Usage |
|---|
dc_live_ | Production | Real documents, billing enabled |
dc_test_ | Testing | Test data, no billing |
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.
- 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 |
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
