Vai al contenuto principale
Italiano— Scegli una lingua
Menu

ACL e principio del privilegio minimo

Lezione 8 di 12 Aggiornata il 28 luglio 2026 Avanzato
In questa pagina
  1. Il principio del privilegio minimo applicato alle API
  2. Il sistema ACL di xAI
  3. Limiti di frequenza: un ulteriore strato di sicurezza
  4. Una strategia di chiavi per ambiente
  5. Verifica e audit dei permessi
  6. Punti chiave

Il principio del privilegio minimo applicato alle API

Il principio del privilegio minimo è uno dei concetti più antichi nella cybersecurity: ogni componente di un sistema dovrebbe avere accesso solo alle risorse strettamente necessarie al suo funzionamento. L’idea è intuitiva se la riporti nel mondo fisico: non dai la chiave master dell’edificio alla persona che annaffia le piante della hall. Applicato alle chiavi API di xAI, questo significa che ogni chiave deve essere limitata solo agli endpoint e ai modelli di cui l’applicazione che la utilizza ha effettivamente bisogno. Se questa chiave dovesse mai trapelare, l’attaccante erediterà i suoi permessi: una chiave ristretta alla chat con un singolo modello causa infinitamente meno danni di una chiave che apre l’intero catalogo.

xAI implementa questo principio attraverso un sistema granulare di ACL (Access Control List), che dettagliamo di seguito.

Il sistema ACL di xAI

Le ACL seguono il formato api-key:{type}:{value}. Due tipi ti riguardano quotidianamente: api-key:endpoint:{endpoint} limita gli endpoint accessibili, mentre api-key:model:{model_id} limita i modelli utilizzabili. Esiste anche un carattere jolly, api-key:endpoint:*, che concede accesso a tutti gli endpoint: comodo per lo sviluppo, proibito in produzione, proprio perché annulla il beneficio del privilegio minimo.

Gli endpoint che puoi autorizzare singolarmente sono: chat (completamento chat, di gran lunga il più comune), embed (generazione di embedding), image (generazione e modifica di immagini), models (consultazione dell’elenco dei modelli), tokenize (tokenizzazione del testo), documents (gestione documenti) e sample (campionamento).

Vediamo come appare tutto questo in un esempio reale. Immagina un chatbot per il supporto clienti che utilizza solo il modello grok-4.3 in modalità chat. La sua chiave ideale assomiglia a questa:

{
  "name": "support-chatbot-prod",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.3"
  ],
  "qps": 5,
  "qpm": 100,
  "tpm": 500000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Leggi questa configurazione come un contratto: la chiave può accedere solo all’endpoint chat—niente immagini, niente embedding, quindi nessun possibile abuso per tali scopi. Può utilizzare solo grok-4.3, il che previene chiamate accidentali (o maliziose) a modelli più costosi. È limitata a 5 richieste al secondo e 100 al minuto, e scadrà in una data nota. Se uno sviluppatore del progetto provasse mai ad aggiungere la generazione di immagini senza dirlo a nessuno, l’API rifiuterà: il vincolo tecnico impone la decisione architetturale.

Limiti di frequenza: un ulteriore strato di sicurezza

Le ACL rispondono alla domanda “cosa”, i limiti di frequenza rispondono a “quanto”. QPS (Query Per Secondo) limita le richieste al secondo: questa è la tua salvaguardia contro picchi accidentali—il ciclo infinito introdotto da un refactoring il venerdì sera, o un attacco DDoS che rimbalza sulla tua applicazione. QPM (Query Per Minuto) distribuisce il traffico su un periodo più lungo e individua abusi che resterebbero sotto il radar del QPS. TPM (Token Per Minuto), infine, limita il volume di token consumati: protegge contro richieste individuali molto lunghe—un utente che incolla un documento di 200 pagine nel tuo chatbot—che esaurirebbero il tuo budget in minuti senza mai superare il numero autorizzato di richieste.

Una strategia di chiavi per ambiente

In pratica, non configuri una singola chiave ma una famiglia di chiavi, e ogni ambiente ha la sua logica. In sviluppo, inverti la logica di produzione: accesso ampio, limiti stretti.

{
  "name": "dev-team-alpha",
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 2,
  "qpm": 30,
  "tpm": 100000,
  "expireTime": "2026-06-30T23:59:59Z"
}

Gli sviluppatori possono esplorare tutto, ma limiti bassi evitano sorprese di fatturazione se un test va male. In staging, al contrario, replichi esattamente le ACL di produzione (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): questo è l’unico modo per rilevare a monte un problema di permessi—se il codice in staging tenta una chiamata che la produzione rifiuterà, è meglio scoprirlo ora piuttosto che nella prima ora del go-live. La chiave di produzione, invece, combina i permessi rigorosi dello staging con limiti dimensionati per il traffico reale (ad esempio QPS 20, QPM 600, TPM 2000000) e una scadenza programmata—"expireTime": "2027-03-31T23:59:59Z" su una chiave chiamata prod-chatbot-v2.

Verifica e audit dei permessi

Per vedere cosa una chiave attiva può effettivamente fare, interroga l’API con la chiave stessa:

curl https://api.x.ai/v1/api-key \
  -H "Authorization: Bearer $XAI_API_KEY"

La risposta elenca le ACL effettive, gli stati api_key_blocked e api_key_disabled, una versione mascherata della chiave (redacted_api_key) e il team_id. Prendi l’abitudine di confrontare regolarmente queste ACL con le esigenze reali dell’applicazione: i permessi tendono ad accumularsi nel tempo, non si riducono mai spontaneamente. Sul fronte dei modelli, l’endpoint GET /auth/teams/{teamId}/models restituisce l’elenco dei modelli disponibili per il tuo team con i relativi prezzi—informazioni preziose per definire ACL sui modelli pertinenti ed escludere modelli costosi che non utilizzi.

Per consolidare tutto ciò, esegui un audit completo delle tue chiavi. Elenca le chiavi attive per ogni team, quindi interroga ciascuna di esse: le sue ACL sono minime, senza caratteri jolly in produzione? I suoi limiti di frequenza sono ragionevoli? La sua data di scadenza è impostata? Il suo nome identifica l’applicazione e l’ambiente—“prod-chatbot-v2” racconta una storia, “key-test-2” non ne racconta nessuna? Elimina le chiavi orfane e documenta il risultato: questo documento servirà come punto di partenza per il prossimo audit e vedrai a colpo d’occhio cosa è cambiato nel frattempo.

Punti chiave

  • Ogni chiave deve avere ACL restrittive: solo endpoint e modelli necessari
  • Mai usare un carattere jolly * in produzione
  • Combina le ACL con limiti di frequenza (QPS, QPM, TPM) adattati all’uso reale
  • Crea chiavi distinte per ambiente (dev, staging, prod) e per applicazione—staging con le stesse ACL di prod
  • Audita regolarmente i permessi sulle tue chiavi attive tramite GET /v1/api-key