Rotazione delle chiavi e ciclo di vita
In questa pagina
Perché la rotazione delle chiavi è essenziale
Un’obiezione comune durante le sessioni di formazione è: «La mia chiave non è mai stata compromessa, perché cambiarla?». La risposta si riduce a una parola: incertezza. Non puoi mai dimostrare che una chiave non sia stata esposta: un log verboso dimenticato su un server, uno screenshot condiviso in un ticket di supporto, una workstation di sviluppatore compromessa sei mesi fa. La rotazione regolare trasforma questa incertezza in un rischio delimitato: anche se una chiave è stata copiata a tua insaputa, smetterà di funzionare alla prossima rotazione. Questo è esattamente il ragionamento utilizzato dagli auditor SOC 2; si aspettano una politica di rotazione documentata. Questo è ciò che chiamiamo riduzione della superficie di attacco temporale: più a lungo vive una chiave, più ampia è la finestra di sfruttamento per un compromesso silenzioso.
L’API di gestione di xAI è progettata per rendere questa pratica indolore: fornisce un endpoint dedicato che ti permette di ruotare una chiave senza riscrivere le tue configurazioni.
Rotazione tramite l’API di gestione
L’endpoint di rotazione è semplice:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Assicurati di capire cosa fa questa chiamata prima di usarla: genera una nuova chiave segreta per l’ID esistente e invalida permanentemente quella vecchia, mantenendo intatte le ACL, i limiti di frequenza e le configurazioni associate alla chiave. Ciò che coglie di sorpresa i team la prima volta è che la modifica è immediata e irreversibile. Se il tuo backend di produzione sta utilizzando questa chiave quando attivi la rotazione, inizierà a ricevere errori di autenticazione entro pochi secondi. Non c’è periodo di grazia, nessun modo per tornare indietro.
Ecco perché, in produzione, preferisci generalmente una procedura in due passaggi per evitare qualsiasi interruzione. Innanzitutto, crea una nuova chiave tramite POST /auth/teams/{teamId}/api-keys, con esattamente gli stessi permessi di quella vecchia. Quindi verifica la sua propagazione con GET /auth/api-keys/{newKeyId}/propagation: una chiave appena creata non è istantaneamente nota su tutta l’infrastruttura e un deploy troppo precoce genera errori confusi. Successivamente, distribuisci la nuova chiave sui tuoi backend e testa che le chiamate funzionino effettivamente con essa, non solo che il deploy sia terminato senza errori. Solo una volta ottenuta questa conferma dovresti disabilitare la vecchia chiave, o lasciarla raggiungere la sua scadenza, prima di eliminarla permanentemente con DELETE /auth/api-keys/{oldKeyId}.
Questo approccio «nuova chiave poi elimina» ti offre un periodo di sovrapposizione in cui entrambe le chiavi coesistono: se il deploy fallisce su un server, nulla si rompe. La rotazione in loco rimane disponibile se desideri mantenere lo stesso ID chiave:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
In questo caso, pianifica di aggiornare immediatamente i tuoi backend, poiché la vecchia chiave muore nell’istante in cui la chiamata viene completata.
Il ciclo di vita completo di una chiave
Una chiave ben gestita ha una storia in quattro atti. Alla creazione, tramite POST /auth/teams/{teamId}/api-keys, definisci il suo nome, le sue ACL e, questa è l’abitudine da consolidare, la sua data di scadenza:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Una chiave senza expireTime è una chiave che vivrà per sempre se nessuno ci pensa; una chiave con scadenza obbliga il tuo team a porsi la domanda del rinnovo in una data fissa. Segue il monitoraggio: GET /v1/api-key ti informa sullo stato della chiave (api_key_blocked, api_key_disabled) e la console xAI espone utilizzi e anomalie. Per le modifiche a metà vita (rinomina, regolazione delle ACL, inasprimento dei limiti di frequenza, posticipo della scadenza), usa PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Infine, l’eliminazione, DELETE /auth/api-keys/{apiKeyId}, è permanente e irreversibile: qualsiasi applicazione che utilizza questa chiave smette di funzionare istantaneamente. Prima di eliminare, assicurati che nessun servizio dimenticato, come un cron mensile o uno script di reportistica, dipenda ancora da essa.
Quale strategia di rotazione adottare?
La frequenza giusta dipende dalla sensibilità del tuo ambiente. La rotazione mensile è obbligatoria in contesti ad alta sensibilità come la finanza o la sanità, dove la finestra di esposizione deve rimanere minima. La rotazione trimestrale si adatta agli ambienti professionali standard: abbastanza frequente da essere efficace, abbastanza distanziata da non appesantire i team. La rotazione annuale, accoppiata a una data di scadenza definita, è il minimo accettabile: al di sotto di ciò, la tua politica di rotazione non è davvero una politica. In tutti i casi, l’automazione tramite uno script programmato ti salva dal dipendere dalla memoria di un amministratore.
La rotazione guidata da eventi si aggiunge a questa pianificazione, attivata da circostanze piuttosto che da date. La attiverai molto spesso in occasione della partenza di un dipendente che aveva accesso alle chiavi: anche se la separazione è cordiale, la chiave che conosceva deve essere ruotata lo stesso giorno: questa è una regola di igiene della sicurezza, non un segno di sfiducia. Fai lo stesso in caso di sospetta compromissione, un incidente di sicurezza nella tua infrastruttura o un cambio di fornitore che aveva accesso ai tuoi sistemi.
Venti minuti per riprendere il controllo del tuo inventario
Il momento migliore per scoprire lo stato reale delle tue chiavi non è il giorno dell’audit. Quindi elenca ora tutte le tue chiavi con GET /auth/teams/{teamId}/api-keys e identifica quelle senza scadenza, per aggiungere un expireTime. Per ognuna, chiediti se le sue ACL corrispondono allo stretto minimo richiesto dall’applicazione che le utilizza; una chiave creata per un prototipo e riciclata in produzione porta quasi sempre troppi diritti.
Quindi elimina le chiavi inutilizzate, perché ogni chiave attiva è un potenziale vettore di attacco, e una chiave che nessuno ricorda è la peggiore di tutte: nessuno noterà il suo uso anomalo. Concludi documentando chi ha accesso a quale chiave e perché. Questo documento, più delle chiavi stesse, è ciò che tirerai fuori al prossimo audit.
Punti chiave
- L’endpoint
POST /auth/api-keys/{id}/rotateinvalida la vecchia chiave permanentemente, senza periodo di grazia - In produzione, preferisci creare una nuova chiave e poi eliminare quella vecchia per evitare qualsiasi interruzione
- Imposta sempre una data di scadenza sulle tue chiavi
- Automatizza la rotazione con uno script programmato (mensile, trimestrale o annuale in base alla sensibilità)
- Attiva la rotazione immediata in caso di qualsiasi cambio di personale o incidente di sicurezza