Authentication

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

Prefix	Type	Use it for
`gak_live_*`	Workspace API key — live mode	Backend services, CI pipelines, production automation
`gak_test_*`	Workspace API key — test mode	Integration tests, sandboxes — isolated data, no real Stripe charges
`gst_<jwt>`	OAuth session token	The 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

Operation	Method and path	Notes
Mint	`POST /v1/workspaces/{slug}/tokens`	Body carries the requested scope set. The secret value is returned exactly once.
Inspect	`GET /v1/workspaces/{slug}/tokens/{id}`	Returns metadata only — scopes, last-used, created-by. Never the secret.
Rotate	`POST /v1/workspaces/{slug}/tokens/{id}/rotate`	New secret, old secret invalidated. Use for scheduled rotation or breach response.
Revoke	`DELETE /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" }
  }
}

Full scope reference

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

Overview

Resources

Authentication

Pick a token type

Workspace API keys

Lifecycle

Test vs live mode

OAuth 2.1 + PKCE

Scopes

Next

Full scope reference

​Pick a token type

​Workspace API keys

​Lifecycle

​Test vs live mode

​OAuth 2.1 + PKCE

​Scopes

​Next

Full scope reference

Pick a token type

Workspace API keys

Lifecycle

Test vs live mode

OAuth 2.1 + PKCE

Scopes

Next