Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Elencare e modificare le tue chiavi

Lezione 3 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Inventario delle tue chiavi API
  2. Elencare le chiavi
  3. Modificare una chiave esistente
  4. Verificare la propagazione
  5. Scenari comuni
  6. Punti chiave

Inventario delle tue chiavi API

Nel tempo, il tuo team accumula chiavi API per diversi ambienti, progetti e membri del team. L’API di gestione ti consente di elencare tutte le chiavi attive, filtrarle per permessi e modificarne le impostazioni senza doverle ricreare.

Elencare le chiavi

Questo endpoint è il punto di partenza per qualsiasi audit di accesso ed è spesso il luogo in cui scopri il vero inventario: chiavi create per un test otto mesi fa, una chiave intestata a un ex membro del team, due chiavi di produzione di cui nessuno sa quale sia in uso. Elenca prima di creare qualsiasi cosa di nuovo: la chiave di cui hai bisogno potrebbe già esistere.

curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Parametri della richiesta

  • pageSize: numero di chiavi per pagina (per impostazione predefinita, vengono restituite tutte le chiavi)
  • paginationToken: token per recuperare la pagina successiva se il numero di chiavi supera la dimensione della pagina
  • aclFilters: filtra le chiavi in base a permessi specifici

Filtrare per ACL

Puoi recuperare solo le chiavi con un determinato livello di accesso:

# Elenca solo le chiavi con accesso alla chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Questo filtraggio è ciò che rende un audit gestibile anche oltre una dozzina di chiavi. Nella pratica emergono due domande a cui una singola richiesta risponde: chi può chiamare il modello più costoso e quali chiavi possiedono ancora un carattere jolly. La seconda è la più utile: un carattere jolly dimenticato in produzione è l’errore di configurazione più comune e il più silenzioso.

Paginazione

Per i team con molte chiavi, utilizza la paginazione:

# Prima pagina di 10 chiavi
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Pagina successiva con il token ricevuto
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Modificare una chiave esistente

Modificare invece di ricreare non è solo una comodità: la chiave segreta rimane la stessa, quindi non è necessario alcun deployment. Questo ti permette di adeguare i limiti o restringere i permessi senza interruzioni del servizio e, in caso di sospetto, di ridurre i diritti di una chiave in pochi secondi mentre prepari la sua rotazione.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning"
    ],
    "qps": 30,
    "qpm": 1000,
    "tpm": 3000000
  }'

Cosa puoi modificare

  • name: rinomina la chiave per riflettere un cambiamento nell’utilizzo
  • acls: aggiungi o rimuovi permessi (endpoint, modelli)
  • qps / qpm / tpm: regola i limiti di frequenza (rate limits)
  • expireTime: estendi o accorcia il periodo di validità

Cosa non puoi modificare

  • L’identificatore della chiave (api_key_id) rimane fisso
  • La chiave segreta non cambia durante la modifica (usa la rotazione per quello)
  • Il team proprietario non può essere trasferito

Verificare la propagazione

Ecco il dettaglio che spiega metà dei “bug” segnalati dopo una modifica della chiave: la modifica non è istantanea su tutti i server. Una chiave appena creata potrebbe restituire un errore 401 per alcuni istanti; un’ACL ampliata potrebbe non essere ancora attiva, e tu cerchi l’errore nel tuo codice quando avresti solo dovuto aspettare. L’endpoint di propagazione esiste proprio per rimuovere questo dubbio:

curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Questo endpoint restituisce lo stato di propagazione della chiave. Attendi il completamento della propagazione prima di utilizzare la chiave in produzione, specialmente dopo aver modificato le ACL.

Scenari comuni

Aggiornare una chiave da dev a prod

Il passaggio alla produzione è lo scenario di modifica più comune, e il riflesso di creare una nuova chiave in questa occasione è costoso: devi distribuirla ovunque, aggiornare i vault e quella vecchia rimane attiva a tempo indeterminato. Aumentare i limiti sulla chiave esistente evita tutto questo.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-chatbot",
    "qps": 50,
    "qpm": 2000,
    "tpm": 5000000
  }'

Limitare una chiave sospettata di compromissione

In caso di sospetto, l’ordine delle operazioni conta. Restringere prima — ACL vuote, limiti di frequenza a zero — ferma l’emorragia in una singola richiesta, senza rompere nulla in modo irreversibile. La rotazione viene dopo, offline, una volta identificato dove è stata utilizzata la chiave. Fare l’inverso ti lascia con la produzione bloccata e un’indagine da condurre sotto pressione.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acls": [],
    "qps": 0,
    "qpm": 0
  }'

Punti chiave

  • GET /auth/teams/{teamId}/api-keys elenca tutte le chiavi con paginazione e filtraggio ACL
  • PUT /auth/api-keys/{apiKeyId} modifica i parametri senza cambiare la chiave segreta
  • GET /auth/api-keys/{apiKeyId}/propagation verifica che le modifiche siano effettive
  • Usa il filtraggio ACL per auditare regolarmente l’accesso del tuo team
  • Dopo qualsiasi modifica, controlla la propagazione prima di utilizzare la chiave in produzione