Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Creare e configurare una chiave API

Lezione 2 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Perché creare chiavi tramite API
  2. Endpoint di creazione
  3. Esempio completo con curl
  4. Strategie ACL consigliate
  5. Endpoint ACL disponibili
  6. Punti chiave

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] o api-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 expireTime per le chiavi temporanee