Authentifizierung

Schlüsselformat#

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

Ein Schlüssel ist eine alphanumerische Zeichenfolge aus einem 10-stelligen Präfix (öffentliche Kennung im Portal) und einem 40-stelligen Geheimteil. esimoa speichert nur einen SHA-256-Hash, daher wird der vollständige Schlüssel nur einmal bei der Ausstellung angezeigt und kann nicht wiederhergestellt werden.

Sending the key#

Sende den Schlüssel bei jeder Anfrage im Header X-API-Key; Authorization: Bearer wird ebenfalls akzeptiert. Ohne Schlüssel kommt 401 API_KEY_REQUIRED, bei fehlerhaftem oder unbekanntem Schlüssel 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. 1Partnerportal → API-Schlüssel — erstelle einen neuen Schlüssel.
2. 2Gib einen Namen und optional ein Ablaufdatum (zwischen 1 Minute und 3 Jahren ab jetzt) sowie eine IP-Zulassungsliste an.
3. 3Kopiere den Schlüssel sofort — er wird nur einmal angezeigt — und speichere ihn in einem Secret-Manager oder einer Server-Umgebungsvariable.

Standardmäßig kann jedes Konto bis zu 5 aktive Schlüssel haben (Schlüssel, die weder widerrufen noch abgelaufen sind).

Rotating keys#

Beim Rotieren entsteht ein neuer Schlüssel mit demselben Namen, denselben Berechtigungen, derselben IP-Allowlist und demselben Ablaufdatum. Der alte Schlüssel funktioniert noch während der gewählten Übergangsfrist (0–72 Stunden) und läuft dann ab – stelle den neuen Schlüssel in diesem Zeitraum bereit. Bei einer Übergangsfrist von 0 wird der alte Schlüssel sofort gesperrt.

IP allowlist#

Jeder Schlüssel kann auf bis zu 20 IPv4-/IPv6-Adressen oder CIDR-Bereiche beschränkt werden (z. B. 203.0.113.10, 198.51.100.0/24). Eine leere Liste bedeutet keine Einschränkung; Anfragen von anderswo erhalten 403 IP_NOT_ALLOWED. Verwende die ausgehenden IPs deiner Server.

Revoking keys#

Widerrufe einen Schlüssel im Portal, sobald er geleakt wurde oder nicht mehr benötigt wird. Schlüssel werden nicht zwischengespeichert, daher wird schon die nächste Anfrage mit 401 KEY_REVOKED abgelehnt. Im Notfall kann esimoa Schlüssel widerrufen oder ein Konto sperren; jeder Schlüssel eines gesperrten Kontos erhält 403 PARTNER_SUSPENDED.

Member roles#

Nur Mitglieder mit OWNER, ADMIN oder DEVELOPER können Schlüssel ausstellen, rotieren oder widerrufen; alle Mitglieder sehen die Schlüsselliste.