Rotazione delle chiavi API: crea, imposta, testa, finalizza
Come ruotare le chiavi API senza downtime: schema crea, imposta, testa, finalizza, intervalli NIST, secret manager e specifiche Chaingateway.
Verificato da Maurice Sobiera

La rotazione delle chiavi API significa sostituire una chiave attiva con una nuova, secondo una pianificazione o dopo un’esposizione, e poi ritirare la vecchia chiave. Lo schema affidabile prevede quattro passi: crea, imposta, testa, finalizza. Una breve sovrapposizione permette a entrambe le chiavi di funzionare, così le richieste in corso non falliscono. NIST e OWASP raccomandano entrambi di automatizzarla.
Perché dovrei ruotare le chiavi API?
La rotazione riduce il tempo in cui una chiave divulgata resta utile a un attaccante. Ogni chiave API è una responsabilità permanente. Una chiave può trapelare da un file .env committato, da un runner CI compromesso o dal portatile di un ex dipendente. Più a lungo la chiave resta valida, più a lungo la fuga resta sfruttabile.
OWASP classifica questo rischio come NHI7, Long-Lived Secrets, nella sua Non-Human Identities Top 10. Descrive chiavi e token con date di scadenza molto lontane, o senza scadenza. Definisce questi segreti estremamente comuni, perché la rotazione è difficile e le alternative effimere non sempre sono disponibili.
La rotazione conta soprattutto per queste credenziali:
- Chiavi con ambiti ampi, come accesso amministrativo, fatturazione o scrittura sui dati di produzione.
- Credenziali condivise tra più servizi o team.
- Qualsiasi cosa incorporata nel codice lato client, nelle app mobili o nelle integrazioni di terzi.
- Token finiti in un repository pubblico, anche per poco tempo.
Dove possibile, sostituisca la chiave statica con un token a breve durata di OAuth o di un sistema di identità dei workload. Una credenziale che scade da sola non richiede un job di rotazione.
Con quale frequenza dovrei ruotare le chiavi API?
Il NIST fissa un solo numero concreto, e riguarda le chiavi di firma. Il NIST IR 8587 afferma che, per i sistemi ad alto impatto, le chiavi di firma dovrebbero avere un periodo massimo di utilizzo attivo di non più di 90 giorni. Per i sistemi a impatto medio e basso può essere appropriato un periodo più lungo, ma inferiore a un anno. Il rapporto indica anche di documentare i cryptoperiod e di adottare una rotazione automatizzata.
Il NIST non fornisce intervalli per le normali chiavi API. I valori seguenti sono nostri suggerimenti, derivati dall’approccio basato sul rischio del rapporto. Non sono un requisito del NIST.
| Credenziale | Età massima suggerita | Motivo |
|---|---|---|
| Chiavi di firma di sistemi ad alto impatto | 90 giorni (NIST) | Raggio d’azione più ampio |
| Chiavi API da servizio a servizio | Da 30 a 90 giorni | Dipende dall’ambito |
| Token CI/CD | 30 giorni | Spesso hanno accesso al deploy |
| Chiavi API rivolte agli utenti | 90 giorni, e subito dopo un sospetto di esposizione | Esistono molte copie |

La regola alla base della tabella è semplice: più danno può fare una credenziale divulgata, più breve deve essere il suo periodo di utilizzo. Un ciclo manuale di 30 giorni è realistico per una manciata di chiavi. Con decine di servizi serve l’automazione. Il NIST sostiene lo stesso punto. Cryptoperiod più brevi spingono le organizzazioni ad automatizzare la rotazione e a esercitare regolarmente il passaggio di consegne.
Dove dovrei conservare le chiavi API?
Conservi le chiavi in un secret manager che versiona i segreti, esegue hook di rotazione, limita gli accessi e registra ogni lettura. Fogli di calcolo e file .env condivisi non possono fare nulla di tutto questo. Verifichi quattro capacità prima di scegliere:
- Versionamento, così il segreto corrente e il precedente possono coesistere.
- Hook di rotazione che eseguono la funzione di rotazione secondo una pianificazione o un evento.
- Limitazione degli accessi, così l’agente di rotazione non può leggere tutti i segreti.
- Log di audit che registrano chi ha acceduto o ruotato quale segreto.
AWS Secrets Manager supporta la rotazione pianificata tramite una funzione di rotazione. HashiCorp Vault può emettere segreti dinamici che scadono da soli. I servizi di gestione delle chiavi nativi del cloud, legati a ruoli IAM, svolgono la stessa funzione.
Dove l’architettura lo consente, eviti le chiavi statiche. OWASP raccomanda segreti dinamici quando possibile, perché riducono la superficie per il riutilizzo delle credenziali. Le credenziali temporanee di AWS STS o le identità gestite di Azure e Google Cloud scadono dopo minuti o ore, quindi non resta nulla di lunga durata da ruotare.
Che cosa sono i passi crea, imposta, testa, finalizza?
I quattro passi sono lo schema che la cheat sheet OWASP descrive per le funzioni di rotazione serverless. Si applicano a qualsiasi secret manager o script personalizzato.
- Crea: genera una nuova versione del segreto senza toccare quella in uso.
- Imposta: invia la nuova credenziale al servizio dipendente o all’archivio di configurazione.
- Testa: esegui un controllo di integrazione che dimostri che il nuovo segreto autentica.
- Finalizza: promuovi il nuovo segreto ad attivo, e revoca o pianifica la cancellazione di quello vecchio.
Il passo che i team saltano è la sovrapposizione tra “imposta” e “finalizza”. Il NIST la descrive come accettazione sovrapposta di chiavi vecchie e nuove. La rotazione dovrebbe pianificare il passaggio delle chiavi prima della scadenza, così i destinatari accettano entrambe le versioni per un certo periodo. La durata giusta della sovrapposizione dipende dal sistema. Deve essere più lunga della richiesta in corso più lunga e del tempo che i client impiegano per recepire il nuovo valore, inclusa la durata delle cache. Scelga un numero, poi lo testi in staging.
| Attivazione | Caso d’uso migliore | Modello dei permessi |
|---|---|---|
| Pianificata | Cadenza prevedibile, ad esempio 30 o 90 giorni | Ruolo di rotazione limitato a un solo percorso di segreto |
| Basata su eventi | Compromissione rilevata, uscita di un dipendente | Privilegi elevati ma a tempo, revocati dopo l’esecuzione |
| Manuale | Verifiche una tantum, onboarding di un nuovo servizio | Approvazione umana più MFA |
L’agente di rotazione deve avere l’insieme di permessi più ristretto possibile: scrittura su un solo segreto e nient’altro.
Che cosa dovrebbe contenere la mia checklist di rotazione?
Verifichi quattro punti prima di automatizzare qualsiasi cosa.
- Crei una copia di sicurezza del segreto attuale e provi il rollback, così non resta solo teoria.
- Costruisca un test di integrazione che valida la nuova credenziale su un endpoint reale.
- Crei un ruolo di rotazione limitato a esattamente un segreto.
- Registri ogni evento di rotazione nel proprio audit trail.
Tenga d’occhio tre punti di guasto ricorrenti. Le applicazioni mettono in cache le credenziali in memoria e non vedono la nuova chiave finché non si riavviano. I provider limitano la frequenza dell’endpoint di creazione delle chiavi se si ruotano molti segreti in un unico batch. I client non aggiornati continuano a usare una chiave revocata dopo la fine della sovrapposizione.
Registri chi o che cosa ha avviato ogni rotazione, una versione mascherata della vecchia e della nuova chiave, la modalità (pianificata, manuale o di emergenza) e l’esito. Osservi un picco improvviso di richieste da una stessa chiave, chiamate da indirizzi IP o regioni che la chiave non ha mai usato prima, e richieste che usano una chiave che avrebbe già dovuto scadere. Esegua scansioni dei repository alla ricerca di chiavi scritte nel codice e mantenga un inventario, perché una chiave fuori dall’inventario non viene mai ruotata.
Come ruoto le credenziali di Chaingateway?
Un’integrazione Chaingateway ha tre tipi di segreti, e ciascuno ruota in modo diverso.
Il token API autentica le richieste come bearer token. I token si creano nel pannello dell’account, alla voce API Tokens, e a ciascuno si assegna un nome. Usi un nome per ambiente, ad esempio sviluppo, staging e produzione. Per ruotarlo, crei un nuovo token, lo distribuisca tramite il secret manager, verifichi che le richieste riescano, poi ritiri quello vecchio. Per limitare ciò che un token divulgato può fare, attivi la whitelist IP (vedi sotto), così solo gli indirizzi del Suo server possono usarlo.
Il segreto del webhook, chiamato segreto personale, firma ogni webhook tramite l’header X-Signature. La documentazione sulla sicurezza dei webhook afferma che un nuovo segreto ha effetto immediato sulle notifiche webhook. Non si possono far funzionare due segreti dal lato del mittente, quindi la sovrapposizione va gestita dal lato ricevente. Verifichi con il nuovo segreto e con quello vecchio per un breve periodo, poi elimini quello vecchio.
import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous oneconst secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) { return secrets.some((secret) => { const expected = createHmac("sha256", secret).update(txid).digest("base64"); return ( expected.length === received.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received)) ); });}Le notifiche che il Suo server ha rifiutato durante il passaggio compaiono nell’elenco delle notifiche fallite. Chaingateway non le ritenta in automatico. Legga l’elenco con GET /api/v2/{chain}/webhooks/notifications/failed e reinvii ogni voce con POST /api/v2/{chain}/webhooks/notifications/{id}/retry. La guida alla consegna dei webhook lo tratta in modo più dettagliato.
Le password dei wallet proteggono gli indirizzi che ha creato con una password. Può cambiarne una con POST /api/v2/ethereum/addresses/{address}, che richiede old_password e new_password. Lo stesso percorso esiste per le altre catene. Chaingateway non memorizza le password, quindi conservi la nuova nel secret manager prima di cambiarla. Una password smarrita non può essere ripristinata.
A che cosa serve la whitelist IP di Chaingateway?
La whitelist IP è un’impostazione dell’account che limita la Sua chiave API agli indirizzi dei server che Lei elenca. È stata rilasciata il 21 giugno 2021. La attivi nelle impostazioni del pannello dell’account e poi inserisca gli indirizzi consentiti. Una richiesta da qualsiasi altro indirizzo viene rifiutata, anche se la chiave è corretta, quindi una chiave trapelata è inutile da una macchina che Lei non ha elencato.
Aggiunga l’indirizzo del Suo server quando la attiva, altrimenti vengono rifiutate anche le Sue richieste. Elenchi l’indirizzo pubblico che il Suo server presenta a internet. Gli intervalli privati come 10.0.0.0/8 e 192.168.0.0/16 sono definiti nella RFC 1918 e non arrivano mai all’API come origine di una richiesta. Dietro un gateway NAT, elenchi l’indirizzo del gateway. Allora sono consentite tutte le macchine che stanno dietro, non una sola.
La whitelist vale per le richieste che Lei invia all’API. Non vale per i webhook, che vanno da Chaingateway al Suo endpoint. Verifichi i webhook con la firma, come descritto sopra.
Whitelist e rotazione limitano cose diverse. La whitelist limita da dove funziona una chiave rubata. La rotazione limita per quanto tempo funziona. Le usi entrambe. Quando i Suoi server passano a nuovi indirizzi, aggiorni l’elenco prima del passaggio, così il Suo stesso traffico non viene rifiutato.
Quando le chiavi API statiche smettono di avere senso?
Le chiavi statiche sono accettabili per strumenti interni a basso rischio. Quando si espone un’API a partner esterni o si gestiscono dati finanziari, conviene passare a un’autenticazione basata su OIDC o JWT con scadenze brevi. Inizi con un solo servizio a basso traffico. Verifichi che l’automazione della rotazione regga con il traffico reale, poi la estenda. Una politica di rotazione applicata, non solo suggerita, è una delle modifiche operative più efficaci che un team di sicurezza possa fare.

Chaingateway copre Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain e Arbitrum con un’unica API REST e un unico livello di autenticazione, quindi non gestisce un ciclo di vita delle credenziali separato per ogni catena. La funzione webhook copre le notifiche di deposito. I piani partono da 49 € al mese nella pagina dei prezzi, e la prova gratuita di 7 giorni non richiede carta.
Fonti
- Protecting Tokens and Assertions from Forgery, Theft, and Misuse: Implementation Recommendations for Agencies and Cloud Service Providers (NIST IR 8587)
- Secrets Management Cheat Sheet, OWASP
- NHI7:2025 Long-Lived Secrets, OWASP Non-Human Identities Top 10
Consigliati
Domande frequenti
Ruotare una chiave API significa generare una nuova credenziale per sostituire quella attiva, e poi ritirare quella vecchia quando ogni sistema dipendente è passato. Fatta bene, la rotazione è un ciclo automatizzato crea, imposta, testa, finalizza, con una breve sovrapposizione in cui funzionano entrambe le chiavi.
Dipende dal rischio. Il NIST IR 8587 afferma che le chiavi di firma dei sistemi ad alto impatto non dovrebbero restare in uso attivo per più di 90 giorni. Per le normali chiavi API non fornisce un numero, quindi scelga un intervallo in base all’ambito della chiave. Per i token CI/CD e per tutto ciò che ha accesso ampio, più breve è meglio.
La rotazione limita il danno di una credenziale divulgata o rubata, perché riduce il tempo in cui la chiave è valida. OWASP classifica i segreti di lunga durata come NHI7 nella sua Non-Human Identities Top 10.
Automatizzi il processo con un secret manager, segua lo schema crea, imposta, testa, finalizza e mantenga una finestra di transizione in cui la chiave vecchia e quella nuova funzionano entrambe. Così si evita il downtime di passare tutti i servizi dipendenti in una volta.
Sì. Chaingateway firma i webhook con HMAC-SHA256 nell’header X-Signature, così può verificarne l’autenticità. Se cambia il segreto personale, il nuovo segreto si applica subito, quindi il suo ricevitore dovrebbe accettare entrambi i segreti per un breve periodo.
Come scriviamo questi articoli
Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.