Autenticazione

Formato della chiave#

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

Una chiave è una stringa alfanumerica composta da un prefisso di 10 caratteri (identificatore pubblico mostrato nel portale) e da un segreto di 40 caratteri. esimoa conserva solo un hash SHA-256, quindi la chiave completa viene mostrata una sola volta al momento dell’emissione e non può essere recuperata.

Sending the key#

Invia la chiave nell’header X-API-Key a ogni richiesta; è accettato anche Authorization: Bearer. Senza chiave si ottiene 401 API_KEY_REQUIRED, con una chiave non valida o sconosciuta 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. 1Portale partner → Chiavi API — crea una nuova chiave.
2. 2Assegna un nome e, facoltativamente, una scadenza (tra 1 minuto e 3 anni da ora) e un elenco di IP consentiti.
3. 3Copia subito la chiave (viene mostrata una sola volta) e conservala in un gestore di segreti o in una variabile d’ambiente del server.

Per impostazione predefinita, ogni account può avere fino a 5 chiavi attive (chiavi non revocate né scadute).

Rotating keys#

La rotazione crea una nuova chiave con lo stesso nome, ambiti, lista di IP consentiti e scadenza. La vecchia chiave continua a funzionare per il periodo di tolleranza scelto (0–72 ore) e poi scade: distribuisci la nuova chiave entro quel periodo. Un periodo di tolleranza di 0 disattiva subito la vecchia chiave.

IP allowlist#

Ogni chiave può essere limitata a un massimo di 20 indirizzi IPv4/IPv6 o intervalli CIDR (ad es. 203.0.113.10, 198.51.100.0/24). Un elenco vuoto significa nessuna restrizione; le richieste provenienti da altre origini ricevono 403 IP_NOT_ALLOWED. Usa gli IP in uscita dei tuoi server.

Revoking keys#

Revoca una chiave nel portale non appena viene divulgata o non serve più. Le chiavi non vengono memorizzate nella cache, quindi la richiesta successiva viene subito rifiutata con 401 KEY_REVOKED. In caso di emergenza esimoa può revocare chiavi o sospendere un account; tutte le chiavi di un account sospeso ricevono 403 PARTNER_SUSPENDED.

Member roles#

Solo i membri OWNER, ADMIN e DEVELOPER possono emettere, ruotare o revocare le chiavi; tutti i membri possono vedere l’elenco delle chiavi.