> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.chaser.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.chaser.sh/_mcp/server.

# Authentication

How to authenticate with the Chaser API.

## API keys

All public API requests (`/v1/sessions`, `/v1/usage`, `/v1/sessions/:id/*`) are authenticated via Bearer token:

```bash
curl -s https://api.chaser.sh/v1/sessions \
  -H "Authorization: Bearer cha_live_..."
```

The API key identifies a workspace. All sessions and usage are scoped to that workspace.

## Cookie authentication

Dashboard-only endpoints (`/v1/keys/*`, `/v1/billing/topup`, `/v1/audit/stream`) use cookie authentication from your browser session. These endpoints are not accessible via API key.

## Key prefixes

| Prefix | Environment |
|---|---|
| `cha_live_` | Production. Real sessions, real billing. |
| `cha_test_` | Test mode. Sessions are not provisioned. Use this for integration testing of your API client. |

## Error responses

| Status | Code | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid API key. |
| 402 | `payment_required` | Workspace balance is zero. Top up. |
| 403 | `forbidden` | Valid key, but the requested resource belongs to a different workspace. |
| 404 | `not_found` | Resource doesn't exist (or doesn't belong to your workspace — we don't distinguish). |

## Security

- **Never commit keys to version control.** Use environment variables.
- **Rotate keys periodically.** Use the dashboard's rotate function to create a new key and retire the old one.
- **Use separate keys per environment.** Production, staging, and CI should each have their own key.