Elencare e modificare le tue chiavi
In questa pagina
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-keyselenca tutte le chiavi con paginazione e filtraggio ACLPUT /auth/api-keys/{apiKeyId}modifica i parametri senza cambiare la chiave segretaGET /auth/api-keys/{apiKeyId}/propagationverifica 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