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 and threads
`mail:send`	Send and reply to emails
`mail:manage`	Update labels, delete messages and threads
`vault:read`	List and retrieve credentials, generate TOTP codes
`vault:write`	Store and delete credentials
`identity:sign`	Sign data with the identity's Ed25519 private key
`identity:verify`	Verify signatures against any did:web identity

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.list_threads`, `mail.get_thread`
`mail:send`	`mail.send`, `mail.reply`
`mail:manage`	`mail.update_labels`, `mail.delete_message`, `mail.delete_thread`
`vault:read`	`vault.list`, `vault.get`, `vault.totp`
`vault:write`	`vault.store`, `vault.delete`

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