Authentication (Developer Reference)

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

Endpoint	Method	Purpose
`GET /v1/auth/authorize`	GET	OAuth authorization endpoint (browser redirect)
`POST /v1/auth/token`	POST	`AuthService.ExchangeToken` — code → tokens
`POST /v1/auth/token/refresh`	POST	`AuthService.RefreshToken` — refresh → new access token
`POST /v1/auth/token/revoke`	POST	`AuthService.RevokeToken` — invalidate a token

Headers

Header	Format	Used by
`Authorization`	`Bearer <access_token>`	OAuth-authenticated requests
`x-api-key`	`<api_key_secret>`	API-key requests
`Content-Type`	`application/json`	Every 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

Situation	What happens
Both `Authorization` and `x-api-key` sent	`ERROR_CODE_INVALID_REQUEST`
Expired access token	`ERROR_CODE_UNAUTHENTICATED` — refresh and retry
Refresh token used twice (after rotation)	`ERROR_CODE_UNAUTHENTICATED` — re-prompt user
API-key request to a stream-acquire endpoint	`ERROR_CODE_PERMISSION_DENIED` — wrong credential type
OAuth token without the `stream` scope on `Acquire*Stream`	`ERROR_CODE_PERMISSION_DENIED`

Usage / Authentication — narrative walkthrough.
OAuth Scopes — what each scope grants.
API Keys — server-to-server credential lifecycle.
Errors — error code reference.

Getting Started

Usage

Platform & Features

Music

Video & Soundtrack

User & Developer

AI & Agents

Developer Guide

Legal

Authentication (Developer Reference)

Endpoint summary

Headers

OAuth — wire-level

Authorization request

Token exchange

Refresh

Revoke

Token introspection

Edge cases

​Endpoint summary

​Headers

​OAuth — wire-level

​Authorization request

​Token exchange

​Refresh

​Revoke

​Token introspection

​Edge cases

​Related

Endpoint summary

Headers

OAuth — wire-level

Authorization request

Token exchange

Refresh

Revoke

Token introspection

Edge cases

Related