Scopes

Scopes control what an identity's API key can do. They are set when creating an identity.

Available Scopes

Scope	Allows
`mail:read`	Read messages, threads, and attachments
`mail:send`	Send and reply to emails
`mail:manage`	Update labels on messages and threads, delete messages and threads, manage allow/block rules
`vault:read`	List and retrieve credentials, generate TOTP codes
`vault:write`	Store, update, and delete credentials; consume TOTP backup codes
`identity:sign`	Sign data as this identity
`identity:verify`	Verify signatures against any identity
`calendar:read`	List and view calendar events
`calendar:write`	Create and update calendar events
`calendar:delete`	Delete calendar events
`calendar:public`	Toggle public calendar visibility
`payments:spend`	Pay x402-priced URLs and MCP tools in USDC under your mandate caps
`slack:read`	Read Slack connection status, list channels, poll stored messages (admin preview)
`slack:send`	Connect/disconnect the Slack workspace, send messages (admin preview)
`social:read`	List connected social accounts and check post results (admin preview)
`social:write`	Create and schedule social posts (admin preview)

If an API key attempts an action outside its scopes, the API returns 403 Forbidden:

{
  "error": "forbidden",
  "message": "Missing required scope: mail:send",
  "status": 403
}

When using the MCP server, only tools matching the identity's scopes are available:

Scope	MCP Tools
Always available	`identity.whoami`
`identity:sign`	`identity.sign`
`identity:verify`	`identity.verify`
`mail:read`	`mail.list_messages`, `mail.get_message`, `mail.get_attachment`, `mail.list_threads`, `mail.get_thread`
`mail:send`	`mail.send`, `mail.reply`
`mail:manage`	`mail.update_labels`, `mail.update_thread_labels`, `mail.delete_message`, `mail.delete_thread`, `mail.list_rules`, `mail.add_rule`, `mail.delete_rule`
`vault:read`	`vault.list`, `vault.get`, `vault.totp`
`vault:write`	`vault.store`, `vault.delete`, `vault.totp_use_backup`
`calendar:read`	`calendar.list`, `calendar.get`
`calendar:write`	`calendar.create`, `calendar.update`
`calendar:delete`	`calendar.delete`
`calendar:public`	`calendar.set_public`
`payments:spend`	`payments.pay`, `payments.mandates_create`, `payments.mandates_list`, `payments.mandates_get`, `payments.mandates_revoke` (`payments.activity` is always available)
`slack:read`	`slack_list_channels`, `slack_list_messages`
`slack:send`	`slack_send_message`
`social:read`	`social_list_accounts`, `social_get_post`
`social:write`	`social_post`

Use Case	Recommended Scopes
Read-only monitoring agent	`mail:read`
Agent that reads and responds	`mail:read`, `mail:send`, `mail:manage`
Notification sender only	`mail:send`
Agent with credential access	`mail:read`, `mail:send`, `vault:read`, `vault:write`
Full access agent	All scopes