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

> Bearer token authentication and API key scopes

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

## Authorization Header

```bash theme={null}
Authorization: Bearer dc_live_your_api_key
```

Example request:

```bash theme={null}
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](https://app.doclo.ai/settings/api-keys).

## Scopes

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

| Scope               | Endpoints                   | Description                       |
| ------------------- | --------------------------- | --------------------------------- |
| `flows:read`        | GET /flows, GET /flows/{id} | List and view flow definitions    |
| `flows:execute`     | POST /flows/{id}/run        | Execute flows                     |
| `executions:read`   | GET /runs/{id}              | View execution status and results |
| `executions:cancel` | POST /runs/{id}/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

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing authorization header"
  }
}
```

**Status:** 401 Unauthorized

**Fix:** Add the `Authorization: Bearer <api_key>` header to your request.

### Invalid API Key

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

**Status:** 401 Unauthorized

**Fix:** Verify your API key is correct and hasn't been revoked.

### Insufficient Scope

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

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

### Environment Variables

Store API keys in environment variables:

```bash theme={null}
# .env (never commit this file)
DOCLO_API_KEY=dc_live_your_api_key
```

```typescript theme={null}
const apiKey = process.env.DOCLO_API_KEY;
```

### Key Rotation

Rotate API keys regularly:

1. Generate a new key in the Dashboard
2. Update your application to use the new key
3. Verify the new key works
4. 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
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Error codes reference
  </Card>

  <Card title="Run Flow" icon="play" href="/api-reference/flows/run">
    Execute your first flow
  </Card>
</CardGroup>