API keys

An API key is the credential every authenticated request sends as Authorization: Bearer agy_live_… (or agy_test_…): a prefix naming the mode, a public 16-character key_id, and a 32-character secret. Only a hash of the secret is stored; the secret is shown once, when the key is minted.

Managed in the dashboard. Keys are minted, listed, rotated and revoked in the dashboard; no credential can mint or list credentials. The API has one key operation: DELETE /api_keys/{id} revokes the calling key itself — a kill switch for a leaked key — and needs keys:write.

Scopes are fixed when the key is minted; to change them, mint a new key and revoke the old one. A write scope also grants its read (chatbots:write covers chatbots:read). profile:write is high-risk: only the account owner can grant it, it is confirmed on its own, and a personal access token never carries it. The catalogue, with what each scope grants, is x-agentency-scopes in this document; each operation names the scope it needs in x-agentency-scope.

Modes. A test key (agy_test_) reads and writes the same real account and spends the same message credits as a live key; it differs only in its lower default rate limit (x-agentency-rate-limits).

Rotation and expiry. Rotating mints a successor and keeps the old key working for up to 24 hours (rotation_grace_until; less when the old key expires sooner). A revoked, expired or rotated-out key, or one used from outside its IP allowlist, is 401 UNAUTHENTICATED; the precise reason is recorded in GET /request_logs.

IDs you will meet.

• id — the key's integer id, from GET /me → key.id; the only id DELETE /api_keys/{id} accepts.
• key_id — the public identifier inside the key string. Safe to log; no operation takes it.