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

# Authentication & Quotas

> API key authentication, usage quotas, and pagination.

## Authentication

Self-serve REST, SDK, and CLI requests use a COLA Cloud API key in the
`X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/colas?q=bourbon"
```

Generate API keys at **Dashboard > API Keys** in the [web app](https://app.colacloud.us).

MCP clients may use the same key as a Bearer token:

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

OAuth-based assistant connectors use WorkOS-issued Bearer tokens and are scoped
per connected app. See [Assistant Security and Quotas](/sdks/mcp-security) for
the assistant-specific scope and revocation model.

### SDKs and CLI

Both SDKs require the API key as a constructor argument:

```python theme={null}
client = ColaCloud(api_key="cola_xxxx")           # Python
```

```typescript theme={null}
const client = new ColaCloud({ apiKey: 'cola_xxxx' }); // JavaScript
```

The CLI reads from the `COLACLOUD_API_KEY` environment variable or a persistent config file:

```bash theme={null}
export COLACLOUD_API_KEY=cola_xxxx   # Environment variable
cola config set-key                  # Or configure persistently
```

## Quotas

Usage is metered by **detail views** (single-record lookups) and **list records** (items returned by list/search endpoints). Quotas are per-user across all channels (web app, API, SDKs, CLI, and MCP).

| Tier           | Detail Views/mo | List Records/mo | Burst/min |
| -------------- | --------------- | --------------- | --------- |
| Free           | 200             | 10,000          | 10        |
| Starter (\$39) | 2,000           | 100,000         | 60        |
| Pro (\$99)     | 10,000          | 1,000,000       | 120       |

Upgrade your tier at **Dashboard > API Keys > Upgrade**.

### Quota Headers

Every response includes these headers:

| Header                     | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `X-Detail-Views-Limit`     | Your monthly detail view limit                         |
| `X-Detail-Views-Remaining` | Detail views remaining this month                      |
| `X-List-Records-Limit`     | Your monthly list record limit                         |
| `X-List-Records-Remaining` | List records remaining this month                      |
| `X-Quota-Reset`            | Unix timestamp when quotas reset (first of next month) |

When you exceed a quota, the API returns `429 Too Many Requests` with an `upgrade_url` in the response body. Per-minute burst limits return a `Retry-After` header.

## Pagination

List endpoints support `page` and `per_page` parameters:

| Parameter  | Default | Max | Description      |
| ---------- | ------- | --- | ---------------- |
| `page`     | 1       | —   | Page number      |
| `per_page` | 20      | 100 | Results per page |

Responses include pagination metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1234,
    "pages": 62
  }
}
```

## Error Responses

| Status | Code             | Description                                                  |
| ------ | ---------------- | ------------------------------------------------------------ |
| 401    | `unauthorized`   | Missing or invalid API key or Bearer token                   |
| 404    | `not_found`      | Resource not found                                           |
| 429    | `quota_exceeded` | Detail view, list record, or per-minute burst limit exceeded |

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "API key required. Provide via X-API-Key header or Authorization: Bearer.",
    "details": {}
  }
}
```