> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doclo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes, and security best practices

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

1. Log in to [app.doclo.ai](https://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

<Warning>
  API keys are shown only once. If you lose a key, you'll need to create a new one.
</Warning>

## Using API Keys

### With the SDK

```typescript theme={null}
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:

```bash theme={null}
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

```typescript theme={null}
// 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

<Warning>
  Never expose API keys in client-side code, public repositories, or logs.
</Warning>

### 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

```bash theme={null}
# .env.local (development)
DOCLO_API_KEY=dc_test_...

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

```typescript theme={null}
// 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

<Tip>
  Use separate keys for each deployment (staging, production) to rotate independently.
</Tip>

## 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

```typescript theme={null}
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  |

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Cloud Quickstart" icon="rocket" href="/cloud/quickstart">
    Get started with Doclo Cloud
  </Card>

  <Card title="REST API Reference" icon="code" href="/api-reference">
    Direct API documentation
  </Card>
</CardGroup>