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.