Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Rotazione ed eliminazione delle chiavi

Lezione 4 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Rotazione: Rinnova senza interruzioni
  2. Eseguire una rotazione
  3. Eliminare una chiave
  4. Automatizzare la rotazione
  5. Punti chiave

Rotazione: Rinnova senza interruzioni

La rotazione delle chiavi è una pratica di sicurezza fondamentale. Genera una nuova chiave segreta per sostituire quella vecchia senza eliminare la chiave stessa. Il vecchio segreto viene invalidato immediatamente e in modo permanente.

Eseguire una rotazione

La rotazione risolve un problema che l’eliminazione non può affrontare: rinnovare il segreto senza perdere l’identità della chiave. Le sue ACL, i limiti di frequenza e il nome sopravvivono all’operazione, quindi non devi riconfigurare nulla: cambia solo il segreto nel tuo vault. Questo rende pratica la rotazione regolare; ricreare una chiave richiederebbe di riconfigurare tutto ogni volta.

POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Comportamento della rotazione

  • Il vecchio segreto è immediatamente invalidato: qualsiasi richiesta che lo utilizza fallirà con un errore 401
  • Viene generato e restituito nella risposta un nuovo segreto
  • L’ID chiave (apiKeyId), il nome, le ACL e i limiti di frequenza rimangono invariati
  • Il nuovo segreto viene visualizzato una sola volta: salvalo immediatamente

Processo di rotazione sicuro

Un aspetto di questa procedura merita enfasi perché spesso sorprende gli utenti: il vecchio segreto viene invalidato immediatamente. Non esiste un periodo di grazia in cui entrambi i segreti funzionano. Qualsiasi servizio che utilizza ancora il vecchio valore fallirà un secondo dopo la chiamata. Questo detta l’ordine dei sei passaggi seguenti: prepara il tuo vault prima di attivare la rotazione, non dopo.

  1. Prepara la tua infrastruttura ad accettare una nuova chiave (variabile d’ambiente, vault)
  2. Esegui la rotazione tramite l’API
  3. Aggiorna immediatamente il segreto nel tuo vault
  4. Ridispiega i tuoi servizi con la nuova chiave
  5. Verifica che le richieste abbiano successo con la nuova chiave
  6. Verifica la propagazione tramite GET /auth/api-keys/{apiKeyId}/propagation

Quando ruotare

Tre situazioni innescano la rotazione, ognuna con un’urgenza diversa. Una sospetta perdita richiede una rotazione immediata: un membro del team con accesso alla chiave se ne va, un log contenente una chiave viene esposto pubblicamente o un repository Git contiene una chiave in chiaro. In questi casi, ogni ora di attesa è un’ora di esposizione, quindi ruota prima di completare l’analisi dell’incidente. La rotazione basata su policy è preventiva: ogni 30, 60 o 90 giorni, a seconda dei tuoi requisiti di sicurezza, limita la durata di una chiave che potrebbe essere stata compromessa senza che te ne accorgessi. Infine, i cambiamenti ambientali—migrazione dell’infrastruttura o cambi di provider—sono un’opportunità naturale per ricominciare da capo con chiavi pulite piuttosto che portare quelle vecchie in un contesto per cui non sono state progettate.

Eliminare una chiave

L’eliminazione è permanente e irrevocabile. La domanda da porsi prima di eliminare non è «Questa chiave è compromessa?», ma «Ho ancora bisogno di questo ambito di accesso?». Se la risposta è sì, hai bisogno di una rotazione: neutralizza il segreto esposto preservando la configurazione. L’eliminazione è giustificata solo per una chiave che non è più utile: un progetto interrotto, un fornitore uscito di scena o un ambiente dismesso.

DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Conseguenze dell’eliminazione

  • La chiave e tutti i suoi parametri vengono eliminati permanentemente
  • Tutte le richieste che utilizzano questa chiave falliranno immediatamente
  • L’azione è irreversibile: dovrai creare una nuova chiave con nuovi parametri
  • La cronologia di utilizzo della chiave rimane disponibile nelle analisi

Rotazione vs eliminazione

AspettoRotazioneEliminazione
La chiave esiste ancoraSìNo
Generato nuovo segretoSìNo
ACL preservateSìNo
Limiti preservatiSìNo
ReversibileNo (vecchio segreto perso)No (chiave eliminata)
Utilizzo tipicoRinnovo regolareChiave obsoleta o compromissione confermata

Automatizzare la rotazione

La rotazione automatizzata ha senso solo se la scrittura nel vault fa parte dello stesso script, senza intervento manuale nel mezzo. Altrimenti, sposti semplicemente il rischio: un segreto generato da una macchina e copiato a mano ha più probabilità di finire negli appunti o nella cronologia del terminale rispetto a una chiave creata dalla console.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"

# Rotate
response = requests.post(
    f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)

new_key = response.json()
new_secret = new_key.get("secret")

# Store in your vault (example with a .env file)
# In production, use Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")

Rotazione programmata

Integra la rotazione nella tua pipeline CI/CD o in un job cron:

# Cron example: rotation on the 1st of each month at 3 AM
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Punti chiave

  • POST /auth/api-keys/{apiKeyId}/rotate invalida il vecchio segreto e ne genera uno nuovo
  • L’invalidazione del vecchio segreto è immediata e permanente
  • DELETE /auth/api-keys/{apiKeyId} elimina la chiave irreversibilmente
  • Preferisci la rotazione all’eliminazione per mantenere ACL e limiti esistenti
  • Automatizza la rotazione con uno script e un vault per i segreti
  • Verifica sempre la propagazione dopo una rotazione