Authentication

Key format#

esk_live_<prefix:10>_<secret:40>

A key is an alphanumeric string made of a 10-character prefix (a public identifier shown in the portal) and a 40-character secret. esimoa stores only a SHA-256 hash, so the full key is shown once at issue time and cannot be recovered.

Sending the key#

Send the key in the X-API-Key header on every request; Authorization: Bearer is also accepted. No key returns 401 API_KEY_REQUIRED, and a malformed or unknown key returns 401 INVALID_API_KEY.

# Preferred
X-API-Key: esk_live_AbCdE12345_<40-character secret>

# Also accepted
Authorization: Bearer esk_live_AbCdE12345_<40-character secret>

Issuing keys#

1. 1Partner portal → API keys — create a new key.
2. 2Give it a name and, optionally, an expiry (between 1 minute and 3 years from now) and an IP allowlist.
3. 3Copy the key right away — it is displayed only once — and store it in a secret manager or a server environment variable.

Each account can have up to 5 active keys by default (keys that are neither revoked nor expired).

Rotating keys#

Rotating creates a new key with the same name, scopes, IP allowlist and expiry. The old key keeps working for the grace period you choose (0–72 hours) and then expires — deploy the new key within that window. A grace period of 0 cuts the old key off immediately.

IP allowlist#

Each key can be limited to up to 20 IPv4/IPv6 addresses or CIDR ranges (e.g. 203.0.113.10, 198.51.100.0/24). An empty list means no restriction; requests from elsewhere get 403 IP_NOT_ALLOWED. Use your servers’ egress IPs.

Revoking keys#

Revoke a key in the portal as soon as it leaks or is no longer needed. Keys are not cached, so the very next request is rejected with 401 KEY_REVOKED. In an emergency esimoa can revoke keys or suspend an account; every key of a suspended account gets 403 PARTNER_SUSPENDED.

Member roles#

Only OWNER, ADMIN and DEVELOPER members can issue, rotate or revoke keys; every member can see the key list.