API Keys

API Keys

Programmatic access for CI/CD and automation, as an alternative to the cookie-based session used by the web dashboard.

Using a key

Send it in either header:

X-API-Key: mp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

or

Authorization: Bearer mp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are stored hashed (never in plaintext) — the raw key is only shown once, at creation time.

Permissions

• Org **viewer**s cannot create, list, or revoke API keys (403 Viewers are not permitted to manage API Keys).
• A key inherits the permissions of the user who created it, resolved the same way as RBAC and Permissions describes for any other request — it is not a separate permission model.

Expiration

Set an expiry when creating a key. Once expiresAt is in the past, every request with that key gets 401 API key has expired. Keys without an expiry never expire on their own — revoke unused ones manually.

Rate limiting

Each key has a rateLimit (requests per rolling 60-second window), defaulting to 60 requests/minute. Set it to 0 to disable rate limiting for that key. Once the limit is hit, the server returns 429 Too many requests. Rate limit exceeded. until the window resets.

The limiter tracks usage in-memory per server process — in a multi-instance deployment, each instance enforces the limit independently rather than sharing a global counter.

Usage metrics

Every authenticated request via a key updates requestCount and lastUsedAt on that key (applied asynchronously, so it doesn't add latency to the request). Useful for spotting stale keys that should be revoked.