Cosa farai
- Ruotare una chiave senza tempi di inattività emettendo prima quella sostitutiva e revocando quella vecchia solo dopo averne confermato il funzionamento in produzione.
- Revocare immediatamente una chiave trapelata — la propagazione a tutte le regioni richiede al massimo 60 secondi.
- Memorizzare le chiavi in variabili d'ambiente o in un secret manager, mai nel codice, e ruotarle quando un membro del team con accesso lascia.
Le chiavi API sono bearer token a lunga durata, quindi ruotarle periodicamente — e revocarle immediatamente in caso di fuga — è un'operazione che vale la pena eseguire correttamente. Questo articolo illustra entrambi i casi.
Ruotare una chiave senza tempi di inattività
Rotazione significa emettere una nuova chiave prima di ritirare quella vecchia, in modo che non ci siano interruzioni in cui la tua integrazione non è autenticata.
- Vai su Settings → API keys e clicca su Generate key.
- Dai alla nuova chiave un nome che ne chiarisca lo scopo (ad es.
production-v2). - Scegli lo stesso ruolo della chiave che stai sostituendo.
- Copia il token — viene mostrato solo una volta.
- Aggiorna la tua variabile d'ambiente o il gestore dei segreti con il nuovo token ed esegui il deploy.
- Una volta che la nuova chiave è attiva e ne hai confermato il funzionamento (controlla la colonna Last used — dovrebbe cambiare entro pochi minuti), torna su Settings → API keys e clicca su Revoke sulla vecchia chiave.
Mantieni attiva la vecchia chiave finché non hai la certezza che quella nuova funzioni. Se revochi troppo presto e il deploy non è ancora stato distribuito, il traffico riceverà errori 401.
Revocare immediatamente una chiave trapelata
Se una chiave viene esposta — caricata su un repository pubblico, trapelata nei log, inclusa in un bundle lato client — revocala subito e indaga dopo.
- Settings → API keys, trova la chiave tramite il nome o il prefisso (il prefisso è visibile nella tabella anche se il token completo non lo è).
- Clicca su Revoke. La revoca si propaga a tutte le regioni entro 60 secondi.
- Emetti una chiave sostitutiva e aggiorna i tuoi segreti.
- Controlla il timestamp Last used sulla chiave revocata per stimare per quanto tempo è stata esposta e se è necessario verificare eventuali attività impreviste.
Le chiavi revocate vengono memorizzate nella tabella con un badge revoked in modo da averne traccia. Non possono essere riattivate.
Aggiornare i segreti in sicurezza
Il pattern standard consiste nel memorizzare le chiavi nelle variabili d'ambiente, non nel codice:
# .env.local (never committed)
ELIDO_API_KEY=elido_live_xxx...
import { ElidoClient } from "@elido/sdk";
const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });
Per le pipeline CI, usa il gestore dei segreti della tua piattaforma (GitHub Actions secrets, GitLab CI variables, ecc.) e ruota le chiavi ogni volta che un membro con accesso lascia il team.
Cosa succede alle integrazioni attive
Quando revochi una chiave, ogni richiesta in corso che ha già inviato il token verrà comunque completata — la convalida avviene all'inizio della richiesta, non a metà risposta. Le richieste che iniziano dopo la revoca restituiscono 401 Unauthorized. Gli SDK non riprovano in caso di 401 (si creerebbe un loop), quindi la tua integrazione inizierà a fallire immediatamente.
Pianifica una breve finestra di sovrapposizione: mantieni in vita la vecchia chiave finché non hai confermato che quella nuova è attiva in produzione.
Troubleshooting
401 su una chiave appena creata. Il token mostrato al momento della creazione è la chiave completa, incluso il suffisso segreto. Se hai copiato solo il prefisso dalla tabella (ad es. elido_abc123), non funzionerà — il prefisso è solo per la visualizzazione. Emetti una nuova chiave e copia il token completo.
Il pulsante Revoke non è visibile. La chiave è probabilmente già stata revocata. Le chiavi revocate mostrano un badge revoked e nessun pulsante di azione. Controlla di essere nel workspace corretto — le chiavi sono limitate al workspace.
Finestra di propagazione di 60 secondi. Se hai revocato una chiave e le richieste continuano ad avere successo per un momento, è normale. I nostri nodi edge sincronizzano la revoca tramite Redis pub/sub; il ritardo nel caso peggiore è di circa 60 secondi.
La chiave è scomparsa dall'elenco. Manteniamo le chiavi revocate nella tabella a tempo indeterminato a scopo di audit. Se non riesci a trovarla, controlla di non aver filtrato l'elenco — non c'è un filtro predefinito per le sole chiavi attive, ma una ricerca testuale sul campo del nome nasconderà le righe non corrispondenti.