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

# API Keys

API keys authenticate requests to the public API (`/v1/sessions`, `/v1/usage`, etc.). Keys are created and managed in the [dashboard](https://chaser.sh/dashboard) under **API Keys**.

## Key format

Keys have the prefix `cha_live_` (production) or `cha_test_` (test mode):

```
cha_live_UDA2HG67cZ5GR8sQf66LUAhyQ8sMMTLDrqtaJ_r9UoQ
```

The prefix is visible in list responses. The full secret is shown **once** at creation time. Chaser does not store it in plaintext — if you lose it, rotate or create a new key.

## Using a key

Pass the key as a Bearer token:

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

## Key management (dashboard)

All key management operations use cookie authentication (your dashboard session), not Bearer tokens.

### Create a key

In the dashboard: **API Keys** → **+ Create key**. Enter a name. The full secret is displayed once — copy it immediately.

### List keys

```bash
# Dashboard-only (cookie auth)
curl -s https://api.chaser.sh/v1/keys \
  -H "Cookie: chaser_session=..." | jq
```

Response:

```json
{
  "keys": [
    {
      "id": "68c58c43-dafc-433c-9d19-3719ab740159",
      "name": "production",
      "prefix": "cha_live_qMRiH5q",
      "created_at": "2026-06-01T12:00:00Z",
      "last_used_at": "2026-06-13T11:00:00Z",
      "revoked_at": null
    }
  ]
}
```

### Revoke a key

Immediately disables the key. All requests with this key return `401`.

```bash
curl -s -X DELETE "https://api.chaser.sh/v1/keys/{key_id}" \
  -H "Cookie: chaser_session=..."
```

Returns `204` on success.

### Rotate a key

Creates a new key and marks the old key as revoked with a grace period (default 7 days). During the grace period, both the old and new key work. After the grace period, the old key stops authenticating.

```bash
curl -s -X POST "https://api.chaser.sh/v1/keys/{key_id}/rotate" \
  -H "Cookie: chaser_session=..." \
  -H "Content-Type: application/json" \
  -d '{"grace_days": 7}' | jq
```

Response includes the new key's full secret (shown once):

```json
{
  "id": "a09de99c-8566-4dc3-a056-afdab41c0831",
  "name": "production",
  "prefix": "cha_live_FX5sbg_",
  "secret": "cha_live_FX5sbg_...",
  "created_at": "2026-06-13T12:00:00Z"
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `grace_days` | integer | `7` | Days the old key remains valid. Range: 0–30. 0 = immediate revoke. |

## Best practices

- **One key per environment.** Separate keys for production, staging, and CI. This limits blast radius if a key leaks.
- **Rotate on suspicion.** If a key may have been exposed, rotate it. The grace period lets you update your deployment without downtime.
- **Don't hardcode keys.** Use environment variables or a secrets manager.
- **Scope keys by name.** Use descriptive names (`production-scraper`, `ci-e2e`, `staging-monitor`) so you can identify usage in the `by_key` breakdown.