Skip to main content
Every request to https://api.gavai.app/v1 must carry Authorization: Bearer <token>. Two kinds of token exist: workspace API keys for machine callers and OAuth session tokens for interactive humans. They have different lifecycles, different prefixes, and different ways of being scoped. By the end of this page you will know which token type to pick, how to mint or refresh it, and how scopes gate every endpoint.

​
Pick a token type

PrefixTypeUse it for
gak_live_*Workspace API key — live modeBackend services, CI pipelines, production automation
gak_test_*Workspace API key — test modeIntegration tests, sandboxes — isolated data, no real Stripe charges
gst_<jwt>OAuth session tokenThe official CLI, IDE tooling, any flow where a human signs in
If you are wiring a server to gavAI, you want a workspace API key. If you are building a tool a developer logs into, you want OAuth.

​
Workspace API keys

Workspace API keys are minted in the console or via . Each key is bound to one workspace and one explicit scope set at creation time. Keys do not expire on a timer — they live until you rotate or revoke them. 
curl https://api.gavai.app/v1/me \
  -H "Authorization: Bearer gak_live_xxxxxxxxxxxxx"

​
Lifecycle

OperationMethod and pathNotes
MintPOST /v1/workspaces/{slug}/tokensBody carries the requested scope set. The secret value is returned exactly once.
InspectGET /v1/workspaces/{slug}/tokens/{id}Returns metadata only — scopes, last-used, created-by. Never the secret.
RotatePOST /v1/workspaces/{slug}/tokens/{id}/rotateNew secret, old secret invalidated. Use for scheduled rotation or breach response.
RevokeDELETE /v1/workspaces/{slug}/tokens/{id}Permanent. The key stops working immediately.
The operating discipline: one key per integration, narrowest scopes that integration needs, store the secret in your secret manager, rotate on schedule and on suspected compromise. See API tokens for the full endpoint contract.

​
Test vs live mode

gak_test_* keys operate in a sandbox: isolated data, isolated counters, no real Stripe charges. The endpoint surface is identical between modes — only the effect and the data differ. Use gak_test_* in CI; switch to gak_live_* only for production traffic.

​
OAuth 2.1 + PKCE

The official CLI and any IDE integration use OAuth 2.1 with PKCE to authenticate a human user. The resulting access token (gst_<jwt>) is short-lived; a refresh token handles transparent renewal. The CLI stores credentials at ~/.config/gavai/credentials.json (Linux and macOS) and refreshes automatically when the access token has expired.

​
Scopes

Every endpoint requires a specific scope — for example pages:read or tokens:destructive. Workspace API keys are minted with an explicit scope set. OAuth session tokens inherit the authenticated user’s permissions for the active workspace. The action levels imply each other: :destructive implies :write, and :write implies :read. A token with pages:destructive can do everything a pages:read token can do and more. If a token lacks the required scope, the API returns 403 with error.code = "insufficient_scope" and details.required_scope names the missing scope: 
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token lacks pages:write",
    "details": { "required_scope": "pages:write" }
  }
}

​
Next

Full scope reference

Every endpoint’s required scope, the four action levels, and least-privilege key patterns.