Authentication
API keys, permissions and how requests are checked.
http
Authorization: Bearer gsk_test_...- Keys look like
gsk_test_orgsk_live_followed by 40 random characters. - A key is shown once at creation. Gasket stores a SHA-256 hash and a display prefix; a lost key can't be recovered, only replaced.
- Rotate a key from its card: a new key with the same permissions is issued and the old one revoked in the same step.
- Revoking a key takes effect on the next request, which returns 401 unauthorized.
Permissions (scopes)
| Scope | Allows |
|---|---|
| agents:run | POST /v1/agents/:id/runs, POST /v1/runs/:id/continue |
| agents:read | GET /v1/agents, GET /v1/agents/:id, GET /v1/runs, GET /v1/runs/:id |
| actions:write | POST /v1/actions, POST /v1/actions/:id/result, the MCP server |
| actions:read | GET /v1/actions, GET /v1/actions/:id |
| policies:read | GET /v1/policies |
| activity:read | GET /v1/events, GET /v1/balance |
A request outside a key's scopes returns 403 insufficient_scope. Give each application only what it needs: a website chat needs agents:run and nothing else.
What every request is checked for
- The key exists and isn't revoked.
- The key has the endpoint's scope.
- The key is under 600 requests per minute.
- The agent belongs to the workspace and is in the key's environment.
- The agent is active.
- The workspace has credit and is under its monthly spend limit (for metered requests).
- The body is valid.
NoteKeys belong on servers. Short-lived browser tokens are planned; until then, proxy through your backend.
Something wrong or missing? Tell us · Stuck? Help center