Rotazione ed eliminazione delle chiavi
In questa pagina
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.
- Prepara la tua infrastruttura ad accettare una nuova chiave (variabile d’ambiente, vault)
- Esegui la rotazione tramite l’API
- Aggiorna immediatamente il segreto nel tuo vault
- Ridispiega i tuoi servizi con la nuova chiave
- Verifica che le richieste abbiano successo con la nuova chiave
- 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
| Aspetto | Rotazione | Eliminazione |
|---|---|---|
| La chiave esiste ancora | Sì | No |
| Generato nuovo segreto | Sì | No |
| ACL preservate | Sì | No |
| Limiti preservati | Sì | No |
| Reversibile | No (vecchio segreto perso) | No (chiave eliminata) |
| Utilizzo tipico | Rinnovo regolare | Chiave 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}/rotateinvalida 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