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 the scopes it declares.

Available scopes

The following table lists the available scopes and the endpoints each one unlocks.

Scope	Grants access to
`realtime:start`	Creating and joining sessions — `POST /realtime/session/start` and `POST /realtime/session/prepare-room` — and the usage read for a run (`GET /sessions/{id}/usage`): a session you may start, you may read the usage of
`realtime:dial`	Placing outbound phone calls — `POST /realtime/session/{id}/dial` (API keys only; see Telephony)
`realtime:read`	The recorded-session history (`GET /sessions/*` — list, get, transcript, recordings, usage), provider capabilities, and `GET /projects/default`
`realtime:logs`	Operational diagnostics — `GET /sessions/{id}/timeline`
`realtime:delete`	`DELETE /sessions/{id}`
`support:write`	`POST /support/requests`
`realtime:use`	Deprecated umbrella — implies all five `realtime:*` scopes plus `support:write`. Keys carrying it keep working; no endpoint requires it directly.
`user_tokens:mint`	`POST /api/v1/external/auth/token` and `DELETE /api/v1/external/auth/token/{token_id}` — minting and revoking 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

GET /realtime/verify requires no scope — an under-scoped credential gets a 200 that says it's under-scoped instead of a 403 indistinguishable from a bad key. The /agents, /whoami, and /sessions/import endpoints authenticate with user access tokens, not API keys.

The scopes realtime apps use

realtime:* verbs — each realtime endpoint requires the one verb that matches what it does: realtime:start for session start, realtime:read for reading sessions back, and so on. Without the required verb the call fails with 403.

realtime:use — the deprecated umbrella. A key that carries it acts as though it carried every realtime:* verb plus support:write, so existing keys lose nothing. It is no longer issued: the key-creation dialog offers the verbs individually, and cosmo login mints them explicitly.

Minted end-user tokens carry realtime:start by default — enough to hold a conversation, nothing more. The mint call can add realtime:read, realtime:delete (both project-bound to the end user's own sessions), or the connectors scopes — see token scopes.

user_tokens:mint — required only by the token mint and revoke endpoints. You need it on the server-side key that mints per-user tokens for browsers and distributed apps. A key carrying only this scope can't upload, chat, or join a session, which is what makes it safe as a provisioning credential.

No scope is pre-selected when you create a key — a key carries exactly the scopes you check, and creation requires at least one. Select Voice — start sessions for a key that starts sessions, and add the other voice verbs your integration needs.

Scope failures

A missing scope returns 403 in the standard error envelope, and the message names what was missing:

{
  "error": {
    "type": "api_error",
    "message": "API key missing required scopes: realtime:start"
  }
}

Scope checks are fail-closed — a request whose scope information can't be resolved is rejected with a 403 (Missing scope information) rather than allowed through.

Scope changes

Scopes are listed against each key under Developer platform → API keys on platform.askcosmo.ai. To check a credential from code, call GET /realtime/verify — the response lists the key's scopes and whether it can_start_sessions; cosmo whoami runs the same check from the shell.

Scopes are fixed at creation — to change them, create a new key and revoke the old one (see the rotation sequence).

Minimal privilege

Grant only the scopes a key actually needs. A backend that starts realtime sessions needs the realtime scopes 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.