Authentication

Mittr supports two authentication methods. Both can be used simultaneously.

Include your API key in any of these locations (checked in order):

1. X-API-Key header (recommended)
2. Authorization: Bearer {key} header
3. ?key={key} query parameter (WebSocket only)

curl https://app.mittr.io/api/v1/events \
  -H "X-API-Key: mtr_your_key"

API keys belong to one workspace and may also be limited to one project. See Project scoping.

For browser-based access (dashboard), authenticate via email/password login:

# Login — sets mittr_session cookie
curl -X POST https://app.mittr.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "..."}' \
  -c cookies.txt

# Subsequent requests use the cookie
curl https://app.mittr.io/api/v1/events -b cookies.txt

Sessions expire after 24 hours by default.

Every request runs in exactly one project. Which one depends on the credential:

• API key limited to a project (the key created at signup is limited to the default project): requests always run in that project. Sending X-Project-ID with any other project returns 403.
• API key with no project (keys created with POST /api/v1/api-keys or mittr apikey create): send X-Project-ID to choose a project in your workspace. A project outside your workspace returns 403. Without the header, requests run in the default project.
• Session cookie: send X-Project-ID to choose a project. A project outside your workspace is ignored and the request runs in the default project.

curl https://app.mittr.io/api/v1/endpoints \
  -H "X-API-Key: mtr_your_key" \
  -H "X-Project-ID: your-project-uuid"

Deleting a project revokes the API keys limited to it.

The server checks authentication in order:

1. Session cookie (mittr_session) → if valid, authenticated
2. API key (X-API-Key / Bearer / ?key=) → if valid, authenticated
3. Neither → 401 Unauthorized

These endpoints require no authentication:

• POST /auth/signup, /auth/login, /auth/verify-email
• POST /auth/forgot-password, /auth/reset-password
• POST /auth/accept-invite
• POST /inbound/{pathSuffix} (inbound webhooks)
• POST /webhooks/billing/{provider} (provider-signed)
• GET /health, /health/live, /health/ready
• GET /docs/, /openapi.yaml, /openapi.json