Authentification

Format de la clé#

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

Une clé est une chaîne alphanumérique composée d’un préfixe de 10 caractères (identifiant public affiché dans le portail) et d’un secret de 40 caractères. esimoa ne stocke qu’un hachage SHA-256 : la clé complète n’est affichée qu’une fois lors de son émission et ne peut pas être récupérée.

Sending the key#

Envoyez la clé dans l’en-tête X-API-Key à chaque requête ; Authorization: Bearer est aussi accepté. Sans clé, la réponse est 401 API_KEY_REQUIRED ; une clé mal formée ou inconnue renvoie 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. 1Portail partenaire → Clés API — créez une nouvelle clé.
2. 2Donnez-lui un nom et, si vous le souhaitez, une date d’expiration (entre 1 minute et 3 ans à partir de maintenant) et une liste d’IP autorisées.
3. 3Copiez la clé immédiatement — elle ne s’affiche qu’une seule fois — et conservez-la dans un gestionnaire de secrets ou une variable d’environnement du serveur.

Par défaut, chaque compte peut disposer de 5 clés actives au maximum (clés ni révoquées ni expirées).

Rotating keys#

Le renouvellement crée une nouvelle clé avec le même nom, les mêmes périmètres, la même liste d’IP autorisées et la même expiration. L’ancienne clé fonctionne pendant la période de grâce choisie (0–72 heures), puis expire — déployez la nouvelle clé dans ce délai. Une période de grâce de 0 coupe immédiatement l’ancienne clé.

IP allowlist#

Chaque clé peut être limitée à 20 adresses IPv4/IPv6 ou plages CIDR au maximum (ex. : 203.0.113.10, 198.51.100.0/24). Une liste vide signifie aucune restriction ; les requêtes provenant d’ailleurs reçoivent 403 IP_NOT_ALLOWED. Utilisez les IP sortantes de vos serveurs.

Revoking keys#

Révoquez une clé dans le portail dès qu’elle fuite ou n’est plus utile. Les clés ne sont pas mises en cache : la requête suivante est immédiatement rejetée avec 401 KEY_REVOKED. En cas d’urgence, esimoa peut révoquer des clés ou suspendre un compte ; toutes les clés d’un compte suspendu reçoivent 403 PARTNER_SUSPENDED.

Member roles#

Seuls les membres OWNER, ADMIN et DEVELOPER peuvent émettre, renouveler ou révoquer des clés ; tous les membres peuvent voir la liste des clés.