API keys

Mint a scoped key for programmatic access, send it on every /v1 request, and rotate it the moment it leaks.

Last updated 18 June 2026

Mint a key

Under API keys in the portal (or POST /portal/api-keys), create a key with a label and scopes (the Send=1, Read=2, Contacts=4, Admin=8 bitfield, non-zero). live controls the key prefix (live vs test). The raw key is returned exactly once — copy it now; only a hash is stored.

Send it on every request

Authenticate /v1 calls with the key in a header — X-Api-Key: <key>, or Authorization: Bearer <key> / Authorization: ApiKey <key>. The tenant is resolved from the key. A missing or invalid key fails closed with 401.

Least privilege

Grant only the scopes a key needs. A send-only integration gets Send; a dashboard that reads status gets Read. A key missing the scope a route requires gets 403 — that's a signal to re-mint with the right scope, not to over-grant.

Rotate on leak

Revoke a leaked key immediately (DELETE /portal/api-keys/{id}) and mint a replacement. Because only a hash is stored, Servus can't recover the raw value for you — rotation is the recovery path.