Convalida della chiave di gestione
In questa pagina
Verifica l’integrità delle tue chiavi
La convalida della chiave di gestione è la prima linea di difesa della tua infrastruttura API. Prima di qualsiasi operazione critica—deploy, rotazione, modifiche alla fatturazione—verifica che la tua chiave sia valida e che i suoi permessi siano corretti.
Endpoint di convalida
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La risposta conferma che la chiave è attiva e restituisce il team, i permessi e le date associate. Non trascurare la data di scadenza: questa è l’unica informazione che ti permette di anticipare un’interruzione invece di subirla, poiché una chiave scaduta non ti avvisa: restituisce semplicemente un errore 401 alla prima chiamata successiva.
Casi di errore
- 401 Unauthorized: La chiave non è valida, è scaduta o è stata eliminata
- 403 Forbidden: La chiave è valida ma non dispone dei permessi necessari per l’operazione richiesta
Integrazione nei tuoi script
Verifica all’avvio
Convalidare all’avvio sposta il fallimento dove costa meno. Senza questo controllo, una chiave non valida si manifesta alla prima chiamata utile, ovvero nel bel mezzo dell’elaborazione, talvolta dopo che diversi passaggi sono già stati eseguiti. Con il controllo, lo script si arresta in tre secondi con un messaggio che ne indica la causa.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Checks that the management key is valid."""
try:
response = requests.get(
f"{MANAGEMENT_API}/auth/management-keys/validation",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
timeout=10
)
if response.status_code == 200:
print("Management key valid")
return True
elif response.status_code == 401:
print("ERROR: Management key invalid or expired")
return False
else:
print(f"ERROR: Unexpected status {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"CONNECTION ERROR: {e}")
return False
if not validate_management_key():
sys.exit(1)
Healthcheck periodico
L’healthcheck periodico copre ciò che la convalida all’avvio non rileva: servizi a lunga esecuzione, avviati settimane prima, la cui chiave potrebbe scadere o essere revocata nel frattempo. Un controllo orario è sufficiente: l’endpoint è leggero e non consuma token di inferenza.
#!/bin/bash
# healthcheck-xai.sh — run every hour via cron
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
"https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY")
if [ "$STATUS" != "200" ]; then
echo "ALERT: xAI management key invalid (HTTP $STATUS)"
# Send an alert (PagerDuty, Slack, email)
fi
Audit delle chiavi di inferenza
L’audit periodico risponde a tre domande che nessun alert ti porrà: quali chiavi hanno ancora un accesso wildcard, quali non hanno limiti di frequenza e quali non vengono utilizzate da mesi. Le prime due rappresentano dei rischi, la terza un’opportunità di pulizia, e tutte e tre vengono gestite in un’unica passata.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Audits all API keys for the team."""
response = requests.get(
f"{MANAGEMENT_API}/auth/teams/{TEAM_ID}/api-keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
keys = response.json().get("apiKeys", [])
print(f"=== API Key Audit — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Total number of keys: {len(keys)}")
for key in keys:
name = key.get("name", "Unnamed")
acls = key.get("acls", [])
expire = key.get("expireTime", "Never")
created = key.get("createdAt", "N/A")
# Alerts
warnings = []
# Key with wildcard access
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("TOTAL ACCESS (wildcards)")
# Key without expiration
if expire == "Never" or not expire:
warnings.append("NO EXPIRATION")
# Key without rate limits
if not key.get("qps") and not key.get("qpm"):
warnings.append("NO RATE LIMITS")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Expire: {expire} | {status}")
audit_api_keys()
Checklist di sicurezza delle chiavi
Chiavi di gestione
Le chiavi di gestione controllano tutto il resto: il loro compromesso concede l’accesso per creare, modificare ed eliminare tutte le chiavi di inferenza. Richiedono quindi la massima cautela: archiviazione esclusiva in un vault, mai in chiaro nel codice o nella configurazione versionata; accesso limitato esclusivamente agli amministratori dell’infrastruttura, non agli sviluppatori di applicazioni; e convalida regolare tramite GET /auth/management-keys/validation, idealmente automatizzata come healthcheck. Scoprire una chiave di gestione scaduta proprio quando ne hai urgente bisogno è lo scenario operativo peggiore.
Chiavi di inferenza (chiavi API)
Per le chiavi di inferenza, il principio guida è l’isolamento: ogni applicazione riceve la propria chiave, mai una chiave condivisa tra servizi. Altrimenti, la rotazione di una chiave compromessa interrompe tutti i servizi contemporaneamente e le analisi non permettono più di attribuire i consumi. Ogni chiave include ACL restrittive calibrate sul suo utilizzo effettivo (niente wildcard in produzione), limiti di frequenza dimensionati per il traffico previsto e una data di scadenza quando l’uso è temporaneo: un POC destinato a durare due settimane non ha bisogno di una chiave eterna. L’audit regolare tramite lo script sopra riportato chiude il cerchio: rivela chiavi dimenticate, con privilegi eccessivi o in procinto di scadere prima che diventino problemi.
Principio di separazione dei compiti
Mantieni una chiara separazione tra le chiavi:
| Tipo | Utilizzo | Chi ha accesso |
|---|---|---|
| Chiave di gestione | Amministrazione, fatturazione, analisi | Amministratori infrastruttura |
| Chiave Prod | Chiamate API in produzione | Applicazione di produzione |
| Chiave Staging | Test pre-produzione | Team di sviluppo |
| Chiave Dev | Sviluppo locale | Singolo sviluppatore |
Ogni chiave ha un ambito definito. Se uno sviluppatore lascia il team, viene eliminata solo la sua chiave dev: le altre rimangono intatte.
Punti chiave
GET /auth/management-keys/validationverifica la validità della tua chiave di gestione- Integra la convalida nell’avvio dei tuoi script e nel monitoraggio
- Esegui audit regolari di tutte le chiavi per rilevare accessi troppo ampi
- Separa le chiavi per ambiente e responsabilità
- Genera alert immediati in caso di chiave non valida (scaduta o eliminata)