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:accept`	Accept x402 USDC payments at registered endpoints (REST only — no MCP tools)

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`

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