Managing API keys programmatically

If you're building on Molted, you'll often need to create and manage API keys without the portal -- for example, to hand each of your agents, workers, or end-customers a key scoped to just the mailboxes they should touch. Everything the portal does is available over the REST API.

This page focuses on key management. For the auth model and the portal/ session flow, see Authentication. For provisioning whole accounts programmatically, see Programmatic signup.

Prerequisites

You need one existing API key (mm_live_…) to authenticate the calls below. Create it at signup or in Settings → Access (/app/settings#access). That key's tenant is the tenant every key you mint will belong to -- you can never mint a key for another tenant.

Base URL and auth

All calls go to https://mailbox.molted.email with a Bearer token:

Authorization: Bearer mm_live_your_key

The mailbox host reads your tenant from the key, so the examples carry no tenantId. On https://api.molted.email the key endpoints need it, as a query param for GET/DELETE or in the JSON body for POST/PATCH; whoami returns it:

curl -X POST https://mailbox.molted.email/v1/agent/whoami \
  -H "Authorization: Bearer mm_live_your_key" \
  -H "Content-Type: application/json" -d '{}'
# → { "tenant_id": "tenant-…" }

Mint a scoped key

The minting endpoint is POST /v1/agent/keys. Scope a key three ways:

curl -X POST https://mailbox.molted.email/v1/agent/keys \
  -H "Authorization: Bearer mm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "support-bot",
    "scopeAllMailboxes": false,
    "mailboxScopes": [
      { "mailboxId": "MAILBOX_UUID", "permissions": ["read", "send"] }
    ]
  }'

curl -X POST https://mailbox.molted.email/v1/agent/keys \
  -H "Authorization: Bearer mm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ops",
    "scopeAllMailboxes": false,
    "mailboxScopes": [
      { "mailboxId": "MBX_A", "permissions": ["read", "send"] },
      { "mailboxId": "MBX_B", "permissions": ["read"] }
    ]
  }'

curl -X POST https://mailbox.molted.email/v1/agent/keys \
  -H "Authorization: Bearer mm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "admin-worker",
    "scopeAllMailboxes": true
  }'

Request fields

Response -- the raw key is shown once

{
  "id": "b2707074-…",
  "keyPrefix": "mm_live_xxxxxxxxxxxx",
  "label": "support-bot",
  "status": "active",
  "scopeAllMailboxes": false,
  "createdAt": "2026-06-09T…",
  "rawKey": "mm_live_…"
}

Store rawKey immediately -- it is never retrievable again. Only the prefix is kept server-side.

Permission model

A send-only key is ideal for outbound-only workers (notifications, campaigns) that should never read inbox contents.

Pattern: a key per worker (least privilege)

The common shape for apps built on Molted: provision one narrow key per agent or customer-facing worker, scoped to only what it needs. In TypeScript:

const API = "https://mailbox.molted.email";
const ADMIN_KEY = process.env.MOLTED_API_KEY!; // your bootstrap key

async function mintScopedKey(mailboxId: string) {
  const res = await fetch(`${API}/v1/agent/keys`, {
    method: "POST",
    headers: { Authorization: `Bearer ${ADMIN_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      label: `worker:${mailboxId}`,
      scopeAllMailboxes: false,
      mailboxScopes: [{ mailboxId, permissions: ["read", "send"] }],
    }),
  });
  if (!res.ok) throw new Error(`mint failed: ${res.status} ${await res.text()}`);
  const key = await res.json();
  return key.rawKey; // hand this to the worker; store it securely
}

Each worker then authenticates with its own scoped key. If it ever tries to act on a mailbox outside its scope, the request is rejected with 403 mailbox_scope_denied -- your blast radius stays contained.

The same holds for event feeds and workspace-wide numbers. A scoped key's event stream and the webhooks it creates only receive events from its own mailboxes, and GET /v1/dashboard/delivery-summary counts only its mailboxes' sends. Routes whose data isn't tied to one mailbox refuse a scoped key with 403 mailbox_scope_denied: the dashboard summary, a list's send stats and send history, the dead letter queue, and outcome reporting.

A webhook a scoped key creates keeps the mailboxes it was created with. Narrowing or revoking that key later doesn't change or remove the webhook; manage it with a key that has access to every mailbox, or in the portal.

List, re-scope, and revoke

curl "https://mailbox.molted.email/v1/agent/keys" \
  -H "Authorization: Bearer mm_live_your_key"
# → [{ id, keyPrefix, label, status, scopeAllMailboxes, mailboxScopes, lastUsedAt, createdAt, createdByKeyId }]

Listing needs an all-mailbox key: a mailbox-scoped key gets 403 mailbox_scope_denied.

curl -X PATCH https://mailbox.molted.email/v1/agent/keys/KEY_ID \
  -H "Authorization: Bearer mm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "scopeAllMailboxes": false,
    "mailboxScopes": [{ "mailboxId": "MAILBOX_UUID", "permissions": ["manage"] }]
  }'
# → { "updated": true }

curl -X DELETE "https://mailbox.molted.email/v1/agent/keys/KEY_ID" \
  -H "Authorization: Bearer mm_live_your_key"
# → { "revoked": true }

The list returns each key's mailboxScopes ({ mailboxId, address, permissions }) so you can audit exactly what every key can reach. Re-scoping an unknown or revoked key answers 404 API key not found or revoked; revoking one twice, 404 API key not found or already revoked. Revoking a key that an OAuth consent minted also revokes that app's grant.

CLI: molted auth keys list, molted auth keys update <id> --mailbox <id> --permissions <perms> (or --scope <mailboxId>[:<perms>], repeatable, or --scope-all), molted auth keys revoke <id>. Mailbox IDs come from GET /v1/agent/mailboxes.

Rotation: raw keys can't be re-read, so to rotate you mint a fresh key, swap it into the consumer, then revoke the old one once traffic has moved over.

What a key may do to other keys

A key can only hand out what it has. From an agent key:

• Mint keys within its own scope. An all-mailbox key may mint any key. A label-only request mints an all-mailbox (admin) key, so a scoped key must pass mailboxScopes within its own mailboxes and permissions (manage covers read and send).
• Re-scope only itself or a key it minted, and only to narrow it: the new scope must fit within the key's current scope and the caller's own.
• Revoke itself or a key it minted, ungated. Each key records its minting key as createdByKeyId in the list response (null for keys made in the portal). Revoking any other key is a human decision (loosens: ["another key"]). A session that belongs to an agent (e.g. a CLI login) may revoke any key its user owns, ungated, including one made before a key could record who minted it.

Anything else is a human decision: 403 human_decision_required with a decisionUrl (<portal>/app/decide/api-key/<id>, kind: "api-key", id the key id or new) and a loosens list naming what the change would widen, or a Molted-Deprecation: human-gate warning header while your account is in warn (new accounts start in enforce). Hand the decisionUrl to a person. A person signed in to the portal manages keys as before: the workspace owner any key, another member only keys they created (anything else is 403 Only the tenant owner or this key's creator can perform this action). A session that belongs to an agent (for example a CLI signup) can still mint keys, and may revoke any key its user owns, but may narrow only a key it minted, and can't create or approve adoptions without a person. See Loosening a control.

Narrowing doesn't cascade. If you (or an agent) re-scope a key to fewer mailboxes or permissions, keys that key already minted keep the wider scope they were given -- narrowing the parent doesn't retroactively narrow its children. Audit createdByKeyId on each key in the list response and revoke or re-scope the children yourself if you need the narrowing to propagate.

Workspace-wide routes

Some routes act on the whole workspace rather than one mailbox, so no mailbox permission can cover them. A key scoped to specific mailboxes gets 403 mailbox_scope_denied on them, even with manage on its own mailbox:

• domains: add, verify, delete, skip warmup, change rate limits or tracking;
• provider failover policy and provider health checks;
• billing: setup-link and activate-free;
• alert destinations, including listing them and their deliveries;
• inbound hooks, including listing them, their logs and dry-run tests;
• account settings, humanizer and safety settings (/v1/agent/config/*, /v1/ops/*), resuming the account and updating incidents, and an agent's config;
• contacts, lists and segments: every write (create, update, delete, subscribe, compute);
• suppressions and suppressed domains: removing them, and the full lists;
• consent: granting it;
• agent coordination: registering an agent, leases (including listing them) and consensus requests and votes;
• the event, outcome and deliverability-event ingest routes;
• journeys, templates and experiments: every write, plus journey runs and experiment results.

Changes that only tighten are the exception, so a scoped agent that handles an unsubscribe reply can honour it: adding a suppression or a suppressed domain (including POST /v1/ops/suppressions and its bulk form), recording a consent withdrawal (POST /v1/consent with revokedAt), and unsubscribing an address from a list. A scoped key may make them when it holds send or manage on at least one mailbox; a read-only key gets 403 mailbox_scope_denied.

A key with access to all mailboxes also needs a write-level scope for the changes: manage or admin for the settings above, contacts, lists, segments and removing a suppression; automation, manage or admin for the rest, including the tightening changes. Otherwise it gets 403 insufficient_scope. Keys minted for all mailboxes carry admin, so this only affects older keys narrowed by hand.

Reads of workspace configuration stay open to a scoped key: domains, provider health and policy, billing status, contacts, lists, segments, templates, journeys, experiments, consent status, and checking one address or domain with GET /v1/suppressions/check. Agent analytics (send velocity, deliverability, policy decisions) count only the scoped key's own mailboxes; contact fatigue always counts every mailbox, so a scoped agent sees the contact's full load; suppression analytics need all-mailbox access.

This applies the same through the CLI, the MCP server and the mailbox service as directly against the API. Give an agent that manages shared data (contacts, lists, suppressions) or workspace settings an all-mailbox key.

Errors

See Errors for the full catalogue.

Security

• Treat keys like passwords. Store them in a secrets manager or env vars; never commit them.
• Prefer scoped keys over scopeAllMailboxes: true. Grant the minimum each consumer needs.
• A key only ever acts on its own tenant: the mailbox host takes the tenant from the key, and a tenantId passed on api.molted.email is validated against it, so you cannot mint or manage keys for another tenant.
• Revoke any key you suspect is compromised; revocation takes effect immediately.

Undo what a key changed

Revoking stops a key, but leaves what it already changed. The workspace owner can do both in one step from Settings > Access > Undo changes…: Molted stops the key and every key it created (revokes them, or suspends them until a person reactivates them), then puts back every settings change they made since a time you pick, except suppressions, which it lists for review. A suspended key answers 401 everywhere, like a revoked one, and is listed in GET /v1/me/keys and GET /v1/agent/keys with status: "suspended". No agent key can revoke or rescope a suspended key, not even the key that created it (403 key_suspended): only a person reactivates or revokes it. Keys minting keys can go at most 20 generations deep (422 key_chain_too_deep). See Undo what an agent changed.

Managing everything else programmatically

Key management is one piece. Most of the platform is available over the same Bearer-authenticated API:

• Send & reply -- Sending email, Outbound, Batch operations
• Mailboxes & routing -- Mailboxes, Rules, Threads
• Domains & deliverability -- Domains, Sender addresses, Analytics
• Contacts & compliance -- Contacts, Suppressions, Lists, Segmentation
• Automation -- Journeys, Experimentation
• Real-time -- Events (SSE), Webhooks, Alerts
• Higher-level clients -- the CLI, the MCP server, and framework integrations