API Keys

API keys authenticate requests to the public API (/v1/sessions, /v1/usage, etc.). Keys are created and managed in the 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:

$
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

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

Response:

1
{
2
  "keys": [
3
    {
4
      "id": "68c58c43-dafc-433c-9d19-3719ab740159",
5
      "name": "production",
6
      "prefix": "cha_live_qMRiH5q",
7
      "created_at": "2026-06-01T12:00:00Z",
8
      "last_used_at": "2026-06-13T11:00:00Z",
9
      "revoked_at": null
10
    }
11
  ]
12
}

Revoke a key

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

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

$
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):

1
{
2
  "id": "a09de99c-8566-4dc3-a056-afdab41c0831",
3
  "name": "production",
4
  "prefix": "cha_live_FX5sbg_",
5
  "secret": "cha_live_FX5sbg_...",
6
  "created_at": "2026-06-13T12:00:00Z"
7
}

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.