Authentication - Clatter Labs Docs

The Agent API uses API keys created in the Console. Each request carries two headers:

Authorizationstringrequired

Bearer clsk_...: your API key.

X-Clatter-Accountstringrequired

The Account ID that owns the key, like CL-7K2M9QXA (Console › Settings). Matching is case-insensitive.

Terminal

curl https://api.agent.clatterlabs.xyz/agent-config \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"

Why two headers

A key alone isn't enough: the request must also name the account that owns it. A key that leaks without its Account ID can't be used, and a key sent with someone else's Account ID is refused.

Situation	Response
No `X-Clatter-Account`	`401 missing_account_id`
Account ID doesn't own the key	`401 account_mismatch`
Key wrong or revoked	`401 invalid_api_key`
Key lacks the permission	`403 insufficient_scope`

Permissions

Permission	Endpoints
`runs:write`	`POST /v1/runs`, `POST /v1/runs/{id}/cancel`
`runs:read`	`GET /v1/runs`, `GET /v1/runs/{id}`, `GET /v1/runs/{id}/events`
`account:read`	`GET /v1/account`

GET /agent-config needs no key; with one it also describes the key.

CORS

The API allows cross-origin requests, which is what makes Try it work. That doesn't make it safe to put keys in front-end code: call the API from your server.