OAuth scopes — Hypery Docs

Scopes constrain delegated OAuth tokens. First-party session cookies and personal API keys (ak_…) are not scope-gated — they act as the user.

An OAuth app may only mint scopes that appear in both:

The global allowlist below
The scopes registered on that app

AI scopes

Scope	Grants
`ai:chat`	Chat completions (`/chat/completions`, `/v1/ai/language-model`)
`ai:completions`	Alias for chat completions
`ai:models`	List / inspect models
`ai:images`	Image generation, predictions, `/v1/ai/image-model`
`ai:embeddings`	`POST /api/v1/embeddings` and `/v1/ai/embedding-model`
`ai:audio`	TTS, transcriptions, realtime session mint

Embeddings and audio do not inherit from ai:chat.

Account & billing

Scope	Grants
`read`	Read-oriented management APIs
`write`	Mutating management APIs (where declared)
`billing:read`	Wallet / usage reads
`billing:charge`	`POST /api/v1/usage/charge` (Browserbase, realtime settle, Deepgram, …)

billing:charge is required for usage charges — ai:chat / write alone are rejected.

App configuration

Scope	Grants
`config:store`	Store & sync app-specific config blobs — `GET/PUT/DELETE /api/config/{key}`

config:store is namespaced per app: a token can only read/write blobs stored under its own app id. Values are capped (256 KB/key, 100 keys). Reserve it for apps that sync user settings across devices (e.g. a desktop editor).

Least privilege

Example for a chat + voice + RAG + browser app:

read write ai:chat ai:embeddings ai:audio ai:images ai:models billing:read billing:charge