Skip to main content
The OAuth resource handles token issuance and refresh for interactive callers — by the end of this page you will know the two endpoints, the rotation rules on refresh tokens, and where the wider PKCE flow lives. It implements OAuth 2.1 with PKCE: the pattern the official gavai CLI and any IDE integration use to authenticate a human user. Both endpoints are unauthenticated and do not require an existing bearer token. If you are building a machine-to-machine integration, use workspace API keys (gak_live_* / gak_test_*) instead. The OAuth flow is for tools acting on behalf of a human who signs in interactively.

​
Endpoints

Both endpoints are unauthenticated — no bearer token required. Exchange a PKCE auth code for access + refresh tokens. Rotate a refresh token, returning a new access + refresh pair.

​
The PKCE handshake

The full flow is documented on the Authentication page — these endpoints are steps 2 and 4 of that walkthrough. The summary:

​
The refresh contract

Refresh tokens rotate on every use. A refresh token can be exchanged exactly once — calling /v1/oauth/refresh twice with the same token will fail the second time with 400.
OperationWhat the server returns
Exchange codeaccess_token (gst_<jwt>), refresh_token, expires_in (seconds), token_type ("Bearer")
RefreshSame shape — a fresh access token and a fresh refresh token. The supplied refresh token is invalidated.
Store the new refresh token before retrying anything else. Losing it means re-running the full PKCE handshake.

Authentication

The full handshake, the scope model, and the lifecycle of session tokens vs API keys.