Authentication

All endpoints except GET /health require authentication via Bearer token.

Authorization: Bearer <token>

Mailman supports two authentication mechanisms, checked in order:

API Keys

Static API keys configured on the server. Primarily for backward compatibility and internal tooling.

Customer-Signed JWTs

Customers generate JWT tokens signed with their own private key and register the corresponding public key with Mailman.

Supported Algorithms

Algorithm	Type
ES256	ECDSA (P-256)
ES384	ECDSA (P-384)
RS256	RSA (2048-bit minimum)

Token Claims

{
  "iss": "org-id",
  "sub": "user-or-service-id",
  "iat": 1705312200,
  "exp": 1705315800,
  "inboxes": ["inbox-uuid-1", "inbox-uuid-2"],
  "scopes": ["messages:send", "messages:read"]
}

Claim	Required	Description
iss	Yes	Organization identifier (must match registered key)
sub	Yes	Subject (user or service identity, for audit logging)
iat	Yes	Issued-at timestamp
exp	Yes	Expiration timestamp
inboxes	No	Restrict token to specific inbox UUIDs. If omitted, token has access to all inboxes.
scopes	No	Permission scopes. If omitted, token has all permissions.

Scopes and inbox bindings are independent lists. A token with scopes: ["messages:send", "threads:read"] and inboxes: ["uuid-1"] can send messages from inbox uuid-1 and read threads in inbox uuid-1, but cannot manage webhooks or access other inboxes.

Scopes

Scope	Grants
messages:send	POST /send
messages:read	GET /messages/{id}
threads:read	GET /inboxes/{id}/threads, GET /inboxes/{id}/threads/{id}
threads:delete	DELETE /inboxes/{id}/threads/{id}
webhooks:manage	POST /webhooks, GET /webhooks, DELETE /webhooks/{id}
attachments:read	GET /attachments/{id}
domains:manage	POST /domains, GET /domains, PUT /domains/{id}, DELETE /domains/{id}
inboxes:manage	POST /inboxes, GET /inboxes, PUT /inboxes/{id}, DELETE /inboxes/{id}

Validation Flow

On each request:

1. Extract Authorization: Bearer <token> header
2. Decode JWT header to determine algorithm
3. Try all active public keys matching the algorithm until one verifies the signature
4. Validate exp (reject if expired)
5. Validate iss (must match the key's organization)
6. Extract scopes and check against the requested endpoint
7. Extract inboxes and enforce resource binding (if non-empty, requested inbox must be in the list)

Condition	HTTP Status
Missing/malformed token	401
Signature verification failed	401
Token expired	401
Insufficient scope	403
Inbox not in token's inboxes list	403

Key Management

Register and manage public keys via the auth keys API:

Method	Path	Description
POST	/auth/keys	Register a public key (PEM format)
GET	/auth/keys	List active keys (PEM not returned)
DELETE	/auth/keys/{id}	Revoke a key (sets revoked_at)

Register Key

POST /auth/keys
Content-Type: application/json

{
  "name": "production-signing-key",
  "algorithm": "ES256",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
}

Response: 201 Created

{
  "id": "key-uuid",
  "organization_id": "org-id",
  "name": "production-signing-key",
  "algorithm": "ES256",
  "created_at": "2024-01-15T10:00:00Z"
}

Key Rotation

Multiple keys can be active simultaneously. To rotate:

1. Register the new public key (POST /auth/keys)
2. Switch token issuance to the new private key
3. Wait for old tokens to expire
4. Delete the old public key (DELETE /auth/keys/:id)

Bootstrap

Initial key registration requires a bootstrap mechanism since the API itself requires authentication:

1. Environment variable — MAILMAN_AUTH__BOOTSTRAP_KEY accepts a PEM public key for initial access. Tokens signed with this key have full access (all scopes, all inboxes). Remove the env var after registering a permanent key via the API.
2. Migration seed — Insert the first key directly into the auth_keys table during initial deployment.

Rate Limiting

Two layers of rate limiting protect the API:

Layer	Scope	Default	Mechanism
Request rate	Per API key / JWT	100 req/min	In-memory token bucket (governor)
Volume rate	Per API key / JWT	Configurable	Redis-backed recipients/minute counter

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.