Scopes
API key scope system for Cosmo Realtime.
Scopes
Scopes limit what an API key can do. A key only works on endpoints covered by its assigned scopes, and an endpoint requires all of the scopes it declares.
Scopes
| Scope | Grants access to |
|---|---|
realtime:use | Realtime sessions (/realtime/session/*), agents, models, projects, and voice sessions |
user_tokens:mint | POST /api/v1/external/auth/token — minting end-user tokens |
chat:read | Reading conversations, messages, templates, and artifact metadata |
chat:write | Sending messages |
documents:read | Reading documents |
artifacts:write | Creating and updating artifacts and documents |
resources:read | Reading workspace resources |
resources:write | Creating and updating workspace resources |
connectors:read | Reading connectors and connected apps |
connectors:write | Managing connectors and connected apps |
documents:write | Reserved; not currently required by any endpoint |
The two scopes realtime apps need
realtime:use — required by every realtime endpoint, including session start. Without it the call fails with 403.
user_tokens:mint — required only by the token-minting endpoint. You need it on the server-side key that mints per-user tokens for browsers and distributed apps. A key carrying only this scope cannot upload, chat, or join a session, which is what makes it safe as a provisioning credential.
Neither scope is granted by default. A key created without an explicit scope selection gets chat:read, chat:write, connectors:read, connectors:write, resources:read, resources:write, and artifacts:write — none of which start a session. Select realtime:use explicitly.
Scope failures
A missing scope returns 403 and names what was missing:
{
"detail": "API key missing required scopes: realtime:use"
}Scope checks are fail-closed — a request whose scope information cannot be resolved is rejected with 403 Missing scope information rather than allowed through.
Checking and changing a key's scopes
Scopes are listed against each key under Developer platform → API keys. The API does not expose a /me or /token/introspect endpoint at this time.
Scopes can be changed on an existing key; you do not need to create a replacement to add one.
Minimal privilege
Grant only the scopes a key actually needs. A backend that only starts realtime sessions needs realtime:use alone. A provisioning service that only mints user tokens needs user_tokens:mint alone. Splitting those across two keys limits the blast radius if either leaks.