Security

Authentication

Use API keys for management routes, JWT for mail access, and HMAC for webhooks.

API key

All /v2 routes require x-api-key.

x-api-key: YOUR_API_KEY

Keys come from the MX_API_KEYS env var (comma separated).

JWT

Mail routes use a Bearer token verified by JWKS or HS256.

Authorization: Bearer eyJhbGciOi...

Configure JWT_JWKS_URL or JWT_HS256_SECRET.

HMAC

Webhooks require SHA256 signature of the raw body.

x-dovecot-signature: hex_hmac

Uses DOVECOT_PUSH_HMAC_SECRET.

JWT validation

JWT verification is configured by env vars:

Var Purpose
JWT_JWKS_URLJWKS endpoint for RS256/ES256
JWT_HS256_SECRETShared secret for HS256
JWT_ISSUERExpected issuer
JWT_AUDIENCEExpected audience

Common auth errors

Missing or invalid credentials return 401.

{
  "error": "Unauthorized",
  "hint": "Provide Authorization: Bearer <key> or X-API-Key header"
}

Some routes return { "error": "missing token" } when JWT is absent.