API Reference

Base URL#

All API endpoints are prefixed with /api/v1.

Authentication#

Most endpoints require authentication via one of:

JWT Bearer Token

Authorization: Bearer <access_token>

Obtain tokens via POST /auth/login or POST /auth/register. Access tokens expire after 15 minutes (configurable). Use POST /auth/refresh with the refresh token to get new tokens, and POST /auth/logout to revoke the current session. GET /auth/sso-status returns SSO configuration and password_policy settings.

Browser clients can pass use_cookie: true on login, register, login/resolve, refresh, and sso/exchange: the refresh token is then delivered as an httpOnly cookie (scoped to /api/v1/auth) and omitted from the JSON response, keeping it out of script-readable storage. refresh and logout fall back to that cookie when the body carries no token. API clients that never send the flag keep receiving both tokens in the body.

Session Limit Enforcement

When a user logs in via password and has reached their maximum number of active sessions, the API returns a 409 Conflict instead of automatically revoking the oldest session. The response includes a pending login token and the list of active sessions.

Login Response (409 — Session Limit Reached)

{  "error": "session limit reached",  "code": "session_limit",  "pending_token": "a1b2c3d4...",  "sessions": [    {      "id": "...",      "ip_address": "192.168.1.1",      "user_agent": "Mozilla/5.0 ...",      "last_used_at": "2026-04-28T10:30:00Z",      "created_at": "2026-04-25T08:00:00Z"    }  ],  "limit": 5}

Resolving the Conflict

To complete the login, call POST /auth/login/resolve with the pending token and the ID of the session to revoke:

{  "pending_token": "a1b2c3d4...",  "revoke_session_id": "550e8400-e29b-41d4-a716-446655440000"}

On success, returns the same 200 response as a normal login with user and tokens. If the session limit is still exceeded (race condition), returns another 409 with a fresh pending token and updated session list.

The pending token expires after 5 minutes. SSO logins go through the same interactive flow: the callback redirects to /login#session_conflict=true&pending_token=<token>&limit=<n>, and the frontend fetches the session list with GET /auth/login/pending-sessions?token=<token> before calling POST /auth/login/resolve. Only if the pending-login store (Redis) is unavailable does either path fall back to auto-revoking the oldest session.

The default session limit is 5 per user, configurable via defaults.max_sessions_per_user in config or PUT /admin/platform. Per-user overrides can be set via PATCH /admin/users/:id with max_sessions.

API Key

Authorization: Bearer bb_<your-api-key>

API keys are scoped to a team with specific permissions. See API Keys.

Pagination#

List endpoints support pagination:

GET /inboxes?page=1&per_page=20

Response:

{  "data": [],  "total": 42,  "page": 1,  "per_page": 20,  "total_pages": 3}

Errors#

{"error": "inbox not found", "code": "not_found"}

Rate Limiting#

Headers included in every response:

X-RateLimit-Limit: 100X-RateLimit-Remaining: 99X-RateLimit-Reset: 1709251200

Endpoint Groups#

The domain and team POST .../transfer endpoints require a system admin.

WebSocket Endpoints#

WebSocket endpoints authenticate with a single-use ticket, not the JWT directly. Call POST /api/v1/ws/ticket with your Bearer token to obtain a ticket (a UUID stored in Redis with a 30-second TTL), then connect with ?ticket=<ticket>.

Inbox Stream

GET /ws/inboxes/{inboxId}?ticket=<ticket>

Streams new emails to a specific inbox in real-time. Messages are JSON with type: "email.received" and the email data in data.

Notification Stream

GET /ws/notifications?ticket=<ticket>

Streams all notifications for the authenticated user. Powers the notification bell in the UI. Messages include type (e.g., email.received, inbox.created, inbox.expired) and data with event details.

Admin Stats Stream

GET /ws/admin-stats?ticket=<ticket>

Requires system admin. Streams real-time platform statistics. Messages have type: "admin.stats" with data containing:

Used by the dashboard for live stat updates when auto-refresh is enabled.

OpenAPI Specification#

A machine-readable OpenAPI 3.0 specification is available at:

GET /docs/openapi.json

This can be imported into tools like Postman, Insomnia, or used to generate client SDKs.