Scoped API key

The Sairaph Mail key model

There are two key types, distinguishable on sight by their wire prefix:

• Per-mailbox keys (`sm_live_…`) are bound to one mailbox and come in two roles:
• `read` - read messages, threads, attachments, drafts, search, folders, labels, bounces, and suppressions for that one mailbox.
• `read_write` - everything read can do, plus send/reply, mutate message and thread state, and manage drafts, folders, labels, and suppressions for that mailbox.

A per-mailbox key is *structurally* incapable of holding any tenant-wide (platform) scope - it can never order a domain, change billing, or touch another mailbox.

• Management keys (`sm_mgmt_…`) are tenant-wide, bound to no single mailbox, and carry the `management` role for cross-mailbox operations. By default they are issued with a least-privilege, read-only scope set across the tenant (full read visibility, zero write/send/mutate); broader write capability is an explicit, deliberate choice at issuance, never the silent default. Management keys must carry an expiry - a never-expiring tenant-wide key is not allowed.

Scopes themselves are canonical resource:action strings (for example messages:read, messages:send, domains:read). Mailbox-level scopes can be granted to either key type; platform-level scopes (mailboxes, domains, DNS, billing, account, keys, webhooks, audit) are management-only.

How scoping is enforced

• Expiry - keys can be set to expire in 30d, 90d, 1y, or never (management keys cannot be never). Expired keys stop authenticating.
• Dashboard-only issuance - keys are minted from the dashboard, not over the agent-facing API, so a leaked key can never mint or revoke another. See KEY_USAGE in code-samples.ts.
• Shown once, hashed at rest - the full secret is displayed exactly once at creation; only an Argon2id hash is stored.
• No privilege amplification - when one key mints another, the child's scopes must be a subset of the minter's, and only a human dashboard session may mint a management key.
• Revoke and rotate - any key can be revoked (it stops working on its next request) or rotated in place (new secret, old one grace-revoked, same binding and scopes).

Pass the key as a Bearer token on every REST and MCP call. The same per-mailbox key authenticates both surfaces.

Related terms

• [Programmatic mailbox](/glossary/programmatic-mailbox) - the resource a per-mailbox key is scoped to.
• [Agent mailbox](/glossary/agent-mailbox) - an agent reaches its inbox with a scoped key.
• [Prompt injection (via email)](/glossary/prompt-injection-email) - least-privilege keys bound the damage an injected instruction can do.