Scopes & permissions
The scope catalog, prefix scopes, and fail-closed semantics that make a key a permission boundary.
A scope is the unit of permission on a sky_ key. The key is the boundary: tools
whose required_scopes are not present fail closed. Grant the fewest scopes an
agent needs.
Scope catalog
| Scope | Grants |
|---|---|
account:read | The key's own workspace context and workspace overview — wallet, agents, numbers, calls, SMS, usage. |
wallet:write | Initiate owner-approved purchased-wallet top-ups with create_wallet_topup on full MCP. OAuth consent does not approve a payment or grant REST billing/settings access. |
coverage:read | Coverage, number catalog, agent catalog, requirements. |
agents:read | Read agents, the public agent catalog, and safe configuration such as voice stacks and workflow drafts. |
agents:write | Create and configure agents; set voice stacks. |
trial_calls:write | Create offline synthetic trial fixtures; no live shared-number PIN calling. |
numbers:read | List numbers, read number rules, list phone servers. |
numbers:write | Request numbers, update rules, create/test phone servers. |
calls:read | List calls, read call status. |
calls:write | Place policy-gated outbound calls. |
recordings:read | Read recording metadata, disclosure, and transcripts, including simulation conversation content. |
sms:read | Read SMS conversations and message text. |
sms:send | Send policy-gated SMS. |
policy:evaluate | Evaluate outbound policy and authorize outbound. |
onboarding:read | Read the workspace capabilities. |
onboarding:write | Request workspace capabilities. |
Content scopes are enforced field by field. A tool that mixes content with
other data, such as send_sms or get_simulation_run, stays callable at its
base scope and omits SMS text or conversation content without sms:read or
recordings:read. account_overview never includes SMS message content. Subscribing a webhook to
sms.received or call.extraction.ready needs the matching content scope, and
changing a webhook address needs both. See Content fields.
Prefix scopes
A prefix scope covers every leaf under it. sms:* grants both sms:read and
sms:send; grant the leaf for least privilege, the prefix when the whole group
is genuinely needed.
API keys and OAuth grants
A delegated agent key cannot self-grant billing or control-plane permissions.
Requested API-key scopes are clamped server-side to what the minting credential
holds; workspace keys exclude operator:*, worker_jobs:read,
worker_jobs:write and provider_mutations:*.
An authorized workspace API key can carry wallet:write, so keep its billing
access out of a delegated key unless needed.
OAuth grants are separate from API-key delegation. A full MCP connection can
receive optional wallet:write through explicit consent; it is offered unticked
when neither requested nor already granted. That OAuth token works only on MCP,
not REST billing or settings routes. Each top-up still needs separate owner
approval of the exact amount, currency and purpose. The read-only connector
cannot receive this payment permission. See OAuth permissions.
Fail-closed
No partial execution
A tools/call for a tool whose required_scopes are missing returns
missing MCP scopes: X and does nothing. There is no best-effort fallback.
Every call is also pinned to the key's organization — a mismatched
organization_id is rejected with MCP organization mismatch.
See Authentication & keys for minting, rotating, and revoking keys.