getting started
Authentication
One credential — the Understudy sk_* key — authenticates everything: proxy traffic on the gateway, the control-plane API, and the agent CLI. How you send it depends on which API shape you're speaking.
Sending the key
| surface | how to authenticate |
|---|---|
POST /v1/messages | x-api-key: sk_live_... (Anthropic convention) or Authorization: Bearer sk_live_... |
POST /v1/chat/completions | Authorization: Bearer sk_live_... (OpenAI convention) |
GET /v1/models | Authorization: Bearer sk_live_... |
Your provider key — when you bring one — is never the credential Understudy validates. It travels separately on x-understudy-upstream-key and is forwarded to the upstream provider for that single request.
Key lifecycle
Keys are minted and revoked on the dashboard's API keys page. The plaintext value is returned exactly once at creation and is not retrievable afterward — only the key id and an obfuscated prefix remain visible. Revocation takes effect on live traffic as the gateway's validation cache expires.
What a key is scoped to
Every key belongs to your organization. Requests authenticated with it resolve against your org's projects and workloads, and the captures it produces are attributed to the key id — visible in the dashboard's capture stream, so you can tell environments apart at a glance.
Failure modes
A missing, malformed, revoked, or unknown key fails with 401 authentication_error in the standard error envelope. A valid key used against another organization's resources fails with 403 authorization_error.