Skip to main content
This page is the developer-reference companion to Usage / Authentication. It documents the exact endpoint shapes, header names, error codes, and edge cases.

​
Endpoint summary

EndpointMethodPurpose
GET /v1/auth/authorizeGETOAuth authorization endpoint (browser redirect)
POST /v1/auth/tokenPOSTAuthService.ExchangeToken — code → tokens
POST /v1/auth/token/refreshPOSTAuthService.RefreshToken — refresh → new access token
POST /v1/auth/token/revokePOSTAuthService.RevokeToken — invalidate a token

​
Headers

HeaderFormatUsed by
AuthorizationBearer <access_token>OAuth-authenticated requests
x-api-key<api_key_secret>API-key requests
Content-Typeapplication/jsonEvery request body
Pass either Authorization or x-api-key, never both. Sending both returns ERROR_CODE_INVALID_REQUEST.

​
OAuth — wire-level

​
Authorization request

GET /v1/auth/authorize
  ?client_id=...
  &redirect_uri=...
  &response_type=code
  &scope=read+stream
  &code_challenge=...
  &code_challenge_method=S256
  &state=...
code_challenge_method=S256 is required. The legacy plain method is rejected.

​
Token exchange

POST /v1/auth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "...",
  "redirect_uri": "...",
  "client_id": "...",
  "code_verifier": "..."
}
Response: 
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read stream"
}

​
Refresh

POST /v1/auth/token/refresh
Content-Type: application/json

{
  "refresh_token": "...",
  "client_id": "..."
}
The response may rotate the refresh token — always overwrite your stored value with the latest.

​
Revoke

POST /v1/auth/token/revoke
Content-Type: application/json

{
  "token": "...",
  "token_type_hint": "access_token" | "refresh_token"
}
Idempotent. Revoking an already-revoked token returns success.

​
Token introspection

AuthService includes TokenInfo for inspecting the active token’s scopes and expiration when needed. See sdk/auth/v1/token_info.proto.

​
Edge cases

SituationWhat happens
Both Authorization and x-api-key sentERROR_CODE_INVALID_REQUEST
Expired access tokenERROR_CODE_UNAUTHENTICATED — refresh and retry
Refresh token used twice (after rotation)ERROR_CODE_UNAUTHENTICATED — re-prompt user
API-key request to a stream-acquire endpointERROR_CODE_PERMISSION_DENIED — wrong credential type
OAuth token without the stream scope on Acquire*StreamERROR_CODE_PERMISSION_DENIED