Scopes & permissions

Every developer key carries an explicit list of scopes, checked on every request across REST, MCP, and A2A.

Grammar

A scope is family:action:

apps:read      apps:write
edits:read     edits:write
files:read     files:write
deploy:read    deploy:write
settings:read  settings:write
keys:read      keys:write
webhooks:read  webhooks:write
observe:read
discovery:read

Wildcards: *:* (everything), apps:* (whole family), *:read (every read action).

What needs what

Operation	Required scope
List/inspect apps, read config	`apps:read`
Create / update / clone / delete apps	`apps:write`
Start AI edits (REST, MCP, A2A `message/send`)	`edits:write`
Poll edit status / logs	`edits:read`
Publish, unpublish, rollback, preview deploy	`deploy:write`
Deploy status, release history	`deploy:read`
Domains, services, app auth settings	`settings:write`
App logs / health / errors	`observe:read`
Capabilities, services, A2A agent card	`discovery:read`
Manage keys / webhooks	`keys:write` / `webhooks:write`

Missing scope → 403 with code insufficient_scope naming the scope you need.

App-pinning

Beyond scopes, a key may be pinned to specific apps ("apps": ["uqon8zje"] at mint time). A pinned key:

only sees its pinned apps in list calls,
gets app_not_found for any other app — even apps you own,
cannot create or clone apps (that would escape the pin).

Pinning applies identically on REST, all 29 MCP tools, and A2A (metadata.app_id is re-checked).

Security guarantees

Immutability — a key’s scopes and pins can never be widened after mint; PATCH only renames.
Subset delegation — a key with keys:write can only mint keys with a subset of its own scopes.
Self-management only — a key can rotate/revoke itself, but managing sibling keys requires your Studio session.
One-time secrets — full key material is returned once at mint/rotate; only a hash is stored.
Rotation grace — rotation issues a new key and keeps the old one valid for 24 hours so deployments can roll.

Recommended patterns

Use-case	Key shape
Personal agent (Claude/Cursor)	`:`, optionally pinned to a sandbox app
CI deploy bot	`deploy:write` + `deploy:read`, pinned to the app
Read-only dashboard	`*:read`
Third-party integration	narrowest family scopes + pin, rotated regularly