Mailbox Authentication & Security¶

The credential surface for mailbox holders -- the people who own a user@domain address and use the webmail or the mobile app. It is the third credential tier (alongside API keys / dashboard sessions and operator sessions) and deliberately shares nothing with the other two: its own table (mailbox_sessions), its own cookie names, its own lockout bucket.

Passwords are never checked against a stored copy. Sign-in and password change both verify by IMAP LOGIN against Dovecot, so the API can never disagree with what a mail client would accept.

Presenting the session¶

Two transports, chosen per request:

Every /api/v1/mailbox/* route resolves the session first and answers one of:

Both 403s are checked in that order: a temporary password is never a way around a second factor.

Sign in¶

POST /api/v1/mailbox-auth/login

Unauthenticated by design; rate-limited by IP and by address (a separate lockout bucket from the dashboard's, so failed webmail sign-ins cannot lock an unrelated dashboard account).

Headers

Body

Two-factor prompt. If the mailbox has 2FA enabled, the first successful password check answers 200 with data: {"two_factor_required": true} and no session; retry with two_factor_code. A wrong code is reported exactly like a wrong password.

Example response

{
  "type": "success",
  "msg": "Signed in",
  "data": {
    "token": "S3cUr3...",
    "csrf_token": "c5rf...",
    "expires_at": "2027-02-27T09:14:02.118377+00:00",
    "email_address": "ada@acme.com",
    "email_account": {"id": "01J1ACC0000000000000000000", "email_address": "ada@acme.com", "name": "Ada"},
    "must_change_password": false,
    "password_change_reason": null,
    "client_platform": "ios",
    "idle_timeout_seconds": 2592000
  }
}

The cookies, when set, carry the same absolute lifetime as the row.

Errors

Session lifetimes¶

The idle window is decided once, at sign-in, and stored on the session row (mailbox_sessions.idle_timeout_seconds). Every authenticated request slides expires_at forward by the stored window, capped by the absolute expiry. Rows created before migration 0021 carry the 8-hour default.

Sign out¶

POST /api/v1/mailbox-auth/logout

Revokes the session server-side (the row is kept, marked revoked, so the sessions list can still show it) and clears both cookies. Idempotent. Works for a session parked at the two-factor prompt and for one parked at the forced-password-change screen.

Change password (the holder's own)¶

POST /api/v1/mailbox/security/password

What happens, in order:

1. new_password is checked against the policy (no network work yet).
2. The lockout is consulted -- failed current_password attempts share the sign-in bucket, so a stolen session guessing here locks the sign-in too.
3. current_password is verified against Dovecot.
4. The new bcrypt hash is written; must_change_password is cleared, password_change_reason is nulled, password_changed_at is stamped.
5. Every other session of this mailbox is revoked. The calling session stays signed in.
6. Dovecot's auth cache is flushed for the address, so IMAP/SMTP honour the new password immediately rather than after the 1-hour cache TTL.

Response

{"type": "success", "msg": "Password changed", "data": {"sessions_revoked": 2, "cache_flushed": true}}

cache_flushed: false means the flush call failed (logged); the password is changed regardless and mail clients pick it up within the cache TTL.

Errors

This is the only /api/v1/mailbox/* route (besides sign-out) that accepts a session whose account has must_change_password = true.

Temporary passwords and forced change¶

An administrator resets a mailbox password from the org-admin API:

POST /api/v1/mailboxes/email-accounts/{account_id}/reset-password

Org-scoped like its neighbours: a tenant credential may only reset its own mailboxes and a cross-org id is 404. Every reset -- temporary or not -- bcrypt-hashes the password, revokes all of the mailbox's sessions, flushes Dovecot's auth cache and emits mailbox.password.changed.

{
  "type": "success",
  "msg": "Password reset",
  "data": {
    "account_id": "01J1ACC0000000000000000000",
    "email": "ada@acme.com",
    "must_change_password": true,
    "password_change_reason": "temporary",
    "password_changed_at": "2026-08-31T09:14:02.118377",
    "sessions_revoked": 1,
    "cache_flushed": true
  }
}

The flow a client sees after a temporary reset:

sequenceDiagram
    participant Admin
    participant API
    participant App as Mobile / webmail
    Admin->>API: POST /mailboxes/email-accounts/{id}/reset-password {temporary: true}
    API-->>Admin: 200 must_change_password=true, sessions_revoked=N
    App->>API: POST /mailbox-auth/login (temporary password)
    API-->>App: 200 token, must_change_password=true
    App->>API: GET /mailbox/messages (Bearer token)
    API-->>App: 403 password_change_required
    App->>API: POST /mailbox/security/password {current_password, new_password}
    API-->>App: 200 Password changed
    App->>API: GET /mailbox/messages
    API-->>App: 200

must_change_password, password_change_reason and password_changed_at are also returned in the email-account objects of the org-admin API, so a dashboard can show which mailboxes still hold a temporary password.

Security state¶

GET /api/v1/mailbox/security

{
  "type": "success",
  "msg": "Security retrieved successfully",
  "data": {
    "two_factor_enabled": true,
    "two_factor_confirmed_at": "2026-08-31T12:30:00",
    "two_factor_pending": false,
    "recovery_codes_remaining": 8,
    "protects": "webmail_sign_in_only"
  }
}

Two-factor enrolment¶

Sessions¶

GET /api/v1/mailbox/security/sessions

The mailbox's 50 most recent sessions, newest first:

{
  "id": "01J1SES0000000000000000000",
  "signed_in_at": "2026-08-31T09:14:02",
  "expires_at": "2026-09-30T09:14:02",
  "ip_address": "203.0.113.5",
  "user_agent": "Mailyte iOS/1.0",
  "client_platform": "ios",
  "idle_timeout_seconds": 2592000,
  "revoked": false,
  "active": true,
  "current": true
}

client_platform is what the client declared at sign-in (null when it said nothing recognisable); idle_timeout_seconds is why a native session's expires_at sits weeks out while a browser's sits hours out. current marks the session making the request -- do not offer "sign out this device" for it.

DELETE /api/v1/mailbox/security/sessions/{session_id}

Revokes one other session. 409 cannot_revoke_current for the caller's own (use sign-out); 404 for an id that is not this mailbox's.

error_code registry for this surface¶

Operator notes¶

• Migration 0023_mailbox_password_policy adds email_accounts.must_change_password / password_change_reason / password_changed_at / two_factor_confirmed_at and mailbox_sessions.client_platform / idle_timeout_seconds. Run it before deploying this API version: the session resolver and the login query name those columns. Rebuild the migrate image first -- it goes stale and silently no-ops on old code.
• Every credential change here flushes Dovecot's auth cache through the doveadm HTTP API (DOVEADM_URL, DOVEADM_API_KEY). Without the key the change still lands but IMAP/SMTP honour it only after auth_cache_ttl (1 hour), and responses report cache_flushed: false.
• Native lifetimes: MAILBOX_NATIVE_SESSION_IDLE_DAYS (default 30) and MAILBOX_NATIVE_SESSION_ABSOLUTE_DAYS (default 180). Browser lifetimes are fixed in code.
• A forced change is enforced by the session resolver, so it covers every present and future /api/v1/mailbox/* route automatically; only the two exempt routes opt out, by using a differently built dependency (require_mailbox_for_password_change, require_mailbox_for_logout in worker/api/utils/mailbox_auth.py).