Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Convalida della chiave di gestione

Lezione 13 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Verifica l’integrità delle tue chiavi
  2. Endpoint di convalida
  3. Integrazione nei tuoi script
  4. Audit delle chiavi di inferenza
  5. Checklist di sicurezza delle chiavi
  6. Principio di separazione dei compiti
  7. Punti chiave

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:

TipoUtilizzoChi ha accesso
Chiave di gestioneAmministrazione, fatturazione, analisiAmministratori infrastruttura
Chiave ProdChiamate API in produzioneApplicazione di produzione
Chiave StagingTest pre-produzioneTeam di sviluppo
Chiave DevSviluppo localeSingolo 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/validation verifica 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)