Creare e configurare una chiave API
In questa pagina
Perché creare chiavi tramite API
Creare una chiave manualmente richiede trenta secondi: è proprio per questo che hai bisogno di automazione. Poiché è veloce, lo fai senza riflettere: nessuna convenzione di denominazione, nessun limite di frequenza, solo un jolly “per andare veloci”. Sei mesi dopo, nessuno sa più a cosa serva ogni chiave.
Utilizzare l’API ti obbliga a nominare, definire l’ambito e impostare un limite per ogni chiave, poiché questi sono parametri dello script. La coerenza smette di essere una disciplina da mantenere manualmente e diventa una proprietà del codice. Puoi automatizzare la creazione delle chiavi per i tuoi ambienti (sviluppo, staging, produzione), applicare ACL granulari e definire limiti di frequenza, il tutto direttamente nei tuoi script di deployment o negli strumenti di infrastruttura.
Endpoint di creazione
Per creare una chiave API, invia una richiesta POST al seguente endpoint:
POST /auth/teams/{teamId}/api-keys
Corpo della richiesta
{
"name": "ma-cle-production",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 10,
"qpm": 100,
"tpm": 1000000,
"expireTime": "2026-12-31T23:59:59Z"
}
Parametri dettagliati
name (obbligatorio): un identificatore leggibile per la tua chiave. Scegli un nome descrittivo che indichi l’utilizzo (prod-backend, staging-chatbot, dev-john). Questo nome appare nella console e nei log di utilizzo.
acls (obbligatorio): l’elenco dei permessi concessi a questa chiave. Sono disponibili due formati:
api-key:endpoint:[endpoint]— limita gli endpoint accessibili (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]— limita i modelli utilizzabili (grok-4.20-0309-reasoning, grok-4.3, ecc.)
Il carattere * funge da jolly: api-key:endpoint:* autorizza tutti gli endpoint, api-key:model:* tutti i modelli. Riservalo allo sviluppo locale. In produzione, un jolly significa che una chiave compromessa concede accesso a tutto ciò che il tuo team può fare, inclusi i modelli più costosi che la tua applicazione potrebbe non utilizzare mai.
qps (opzionale): query al secondo — numero massimo di richieste al secondo.
qpm (opzionale): query al minuto — numero massimo di richieste al minuto.
tpm (opzionale): token al minuto — numero massimo di token elaborati al minuto.
expireTime (opzionale): data di scadenza in formato ISO 8601. La chiave verrà disabilitata automaticamente a questa data.
Esempio completo con curl
curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v2",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning",
"api-key:model:grok-4.3"
],
"qps": 20,
"qpm": 500,
"tpm": 2000000,
"expireTime": "2027-06-30T23:59:59Z"
}'
La risposta contiene la chiave segreta, che non verrà mai più visualizzata. Questa regola ha una conseguenza pratica che devi anticipare prima di eseguire lo script, non dopo: se crei chiavi in un ciclo, l’archiviazione deve avvenire contestualmente. Una chiave persa tra la creazione e la registrazione non è recuperabile: devi eliminarla e ricominciare da capo. Scrivila in un vault (Vault, AWS Secrets Manager) piuttosto che sull’output standard del tuo terminale, dove finirebbe nella tua cronologia.
Strategie ACL consigliate
Chiave di sviluppo (ampia)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ideale per lo sviluppo locale: l’accesso è ampio perché non sai in anticipo cosa proverai, ma i limiti di frequenza restano bassi. Questo è il giusto compromesso: un ciclo infinito scritto per errore un venerdì sera costerà pochi centesimi invece di qualche centinaio di euro.
Chiave di produzione (ristretta)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
In produzione, la regola si inverte: parti da ciò che l’applicazione fa effettivamente e autorizza solo quello. La domanda da porsi quando si scrive l’ACL è sempre la stessa: se questa chiave venisse compromessa domani, cosa potrebbe fare un terzo? Una chiave limitata alla chat su un singolo modello e capped a dieci richieste al secondo offre una risposta breve.
Chiave temporanea (con scadenza)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
La scadenza automatica risolve il problema che nessuno gestisce: le chiavi che ci si dimentica di eliminare. Un POC, una dimostrazione, un consulente di passaggio: in tutti questi casi, expireTime garantisce che l’accesso si disattivi da solo. Questo è l’unico modo affidabile per mantenere un inventario pulito, perché non dipende dalla memoria di nessuno.
Endpoint ACL disponibili
Per vedere gli endpoint che puoi utilizzare nelle ACL, consulta:
GET /auth/teams/{teamId}/endpoints
Gli endpoint disponibili sono: chat, embed, image, models, sample, tokenize, documents. Questo elenco può evolversi nel tempo, quindi controllalo regolarmente.
Punti chiave
- La creazione delle chiavi avviene tramite
POST /auth/teams/{teamId}/api-keys - Le ACL seguono il formato
api-key:endpoint:[nome]oapi-key:model:[nome] - Il jolly
*concede accesso completo a tutti gli endpoint o modelli - La chiave segreta viene visualizzata una sola volta alla creazione: salvala immediatamente
- Definisci sempre limiti di frequenza (
qps,qpm,tpm) adeguati all’utilizzo - Usa
expireTimeper le chiavi temporanee