Authentication

Molted Email uses two authentication methods depending on the context.

Session cookies (Portal UI)

When you sign in at molted.email, a session cookie is set. This cookie authenticates all portal requests -- dashboard, domain management, billing, and API key management.

No action is required on your part. The session is managed automatically by the portal.

Bearer API keys (Sending API)

All API requests to api.molted.email require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Managing API keys

1. Go to Dashboard > API Keys in the portal.
2. Click Create Key to generate a new key.
3. Copy the key immediately -- it is displayed only once and cannot be retrieved later.
4. To revoke a key, click Revoke next to the key in the list.

Mailbox-scoped keys

API keys can be scoped to specific mailboxes with granular permissions:

curl -X POST https://api.molted.email/v1/me/keys \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "support-inbox-only",
    "scopeAllMailboxes": false,
    "mailboxScopes": [
      { "mailboxId": "MAILBOX_UUID", "permissions": ["read", "send"] }
    ]
  }'

Set scopeAllMailboxes: true (the default) for a key with full access to all mailboxes.

Per-mailbox permissions:

A key with send only can send from the scoped mailbox but cannot list or fetch its threads — useful for outbound-only agents (notifications, campaigns, alerts). Requests to other mailboxes return 403 mailbox_scope_denied.

Programmatic signup

Agents can create accounts and provision API keys without the portal UI.

Step 1: Create an account

curl -X POST https://api.molted.email/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "name": "My Agent",
    "email": "agent@example.com",
    "password": "secure-password-here"
  }'

This creates a user account and automatically provisions a tenant, default mailbox, and default transactional template. The session cookie is saved to cookies.txt.

Step 2: Get your tenant ID

curl https://api.molted.email/v1/me/tenant \
  -b cookies.txt

{
  "id": "tenant-slug-a1b2c3d4",
  "name": "My Agent",
  "status": "trial"
}

Step 3: Create an API key

curl -X POST https://api.molted.email/v1/me/keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "label": "default",
    "scopeAllMailboxes": true
  }'

{
  "id": "key-uuid",
  "keyPrefix": "mm_live_...",
  "label": "default",
  "rawKey": "mm_live_abc123..."
}

Save rawKey immediately -- it is only returned once. Use it as your Authorization: Bearer token for all subsequent API calls.

Login links

Generate a one-time portal login link to hand off to a human -- for example, when an account owner needs to complete billing setup or manage domains.

CLI

molted auth login-link

No flags required. The command uses your active profile credentials.

{
  "token": "abc123def456...",
  "url": "https://molted.email/auth/token-login?token=abc123def456...",
  "expiresAt": "2026-04-09T14:15:00.000Z"
}

API

POST https://api.molted.email/v1/agent/login-token

Requires Bearer authentication.

curl -X POST https://api.molted.email/v1/agent/login-token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "your-tenant-id"}'

{
  "token": "abc123def456...",
  "url": "https://molted.email/auth/token-login?token=abc123def456...",
  "expiresAt": "2026-04-09T14:15:00.000Z"
}

Response fields

Behavior

• The link expires after 15 minutes.
• The link is single-use -- it is invalidated after the first click.
• Clicking the link signs the human into the portal with full session access (dashboard, billing, domains, API keys).
• If the link is expired or already used, the human is redirected to the standard login page.

Typical workflow

1. Your agent detects that sends are blocked (sendBlocked: true from molted billing status).
2. Run molted auth login-link to generate a portal URL.
3. Send the URL to the account owner so they can complete billing setup.
4. Once billing is activated, sends are automatically unblocked.

Security notes for login links

• Each link grants a full portal session. Only share it with the account owner.
• Links cannot be revoked -- rely on the 15-minute expiry and single-use behavior.
• Generate a new link each time -- do not cache or reuse URLs.

Security notes

• API keys grant full send access to your tenant. Treat them like passwords.
• Store keys in environment variables or a secrets manager. Never commit them to source control.
• Rotate keys periodically. Revoke any key you suspect has been compromised.
• Each key is scoped to a single tenant.