Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Autenticazione con token Bearer

Lezione 14 di 14 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Metti in sicurezza le tue chiamate API
  2. Lo schema Bearer token
  3. Errori di autenticazione
  4. Migliori pratiche di sicurezza
  5. Rilevamento delle fughe di dati
  6. HTTPS obbligatorio
  7. Punti chiave
  8. Verifica la tua comprensione

Metti in sicurezza le tue chiamate API

Guida introduttiva nella documentazione xAI Ogni richiesta inviata all’API xAI deve essere autenticata. L’API utilizza lo schema Bearer token, uno standard ampiamente adottato per le API REST. Questa lezione spiega come funziona il meccanismo e le migliori pratiche per proteggere le tue chiavi in produzione.

Lo schema Bearer token

Come suggerisce il nome, chiunque possieda (“porti”) il token può accedere all’API. Ecco perché proteggere la tua chiave è fondamentale: non esiste alcun controllo d’identità oltre al token stesso.

Formato dell’intestazione

Ogni richiesta HTTP deve includere l’intestazione Authorization con il prefisso Bearer seguito dalla tua chiave:

Authorization: Bearer xai-your-api-key

Con cURL, ottieni:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}'

In Python, gli SDK gestiscono automaticamente questa intestazione quando passi la chiave al costruttore del client.

Errori di autenticazione

HTTP 401 Unauthorized

Questo errore significa che la tua chiave manca, non è valida o è stata revocata. Verifica:

  • Che la variabile d’ambiente XAI_API_KEY sia impostata
  • Che la chiave inizi con xai-
  • Che la chiave non sia stata revocata nella console

HTTP 403 Forbidden

La tua chiave è valida ma non dispone delle autorizzazioni necessarie per l’azione richiesta. Questo può accadere con restrizioni di team su determinate operazioni.

Migliori pratiche di sicurezza

Non esporre mai una chiave nel codice

Le chiavi non devono mai apparire in testo semplice in:

  • Codice sorgente versionato (Git)
  • Log dell’applicazione
  • URL o parametri di query
  • Messaggi di errore mostrati agli utenti
  • Issue e pull request su GitHub

Usa un vault per i segreti

In produzione, archivia le tue chiavi in un sistema dedicato:

  • AWS Secrets Manager o Parameter Store
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Segreti della tua piattaforma CI/CD (GitHub Actions, GitLab CI)

Rotazione delle chiavi

Cambia le tue chiavi regolarmente e immediatamente se sospetti una fuga:

  1. Crea una nuova chiave nella console xAI
  2. Aggiorna la chiave nel tuo vault per i segreti
  3. Ridistribuisci la tua applicazione
  4. Verifica che tutto funzioni con la nuova chiave
  5. Revochi la vecchia chiave nella console

Limita le autorizzazioni

Se lavori in team, crea chiavi separate per ogni servizio e ambiente. Se una viene compromessa, l’impatto rimane limitato a un singolo contesto.

Rilevamento delle fughe di dati

Il prefisso xai- consente agli strumenti di rilevamento (scansione segreti di GitHub, GitGuardian, TruffleHog) di identificare automaticamente le chiavi nel codice sorgente. Attiva questi strumenti nei tuoi repository per essere avvisato immediatamente in caso di esposizione accidentale.

Se una chiave viene rilevata in un commit pubblico:

  1. Revochila immediatamente nella console xAI
  2. Controlla la tua cronologia d’uso per individuare utilizzi fraudolenti
  3. Crea una nuova chiave
  4. Pulisci la cronologia Git (o meglio, considera la chiave compromessa e procedi oltre)

HTTPS obbligatorio

L’API xAI accetta solo connessioni HTTPS. TLS crittografa le tue richieste in transito, inclusa l’intestazione Authorization. Non cercare mai di aggirare questa protezione: una richiesta su HTTP non crittografato esporrebbe la tua chiave sulla rete.

Punti chiave

  • L’API utilizza lo schema Bearer token tramite l’intestazione Authorization
  • La chiave è l’unico fattore di autenticazione: proteggila come una password
  • Usa un vault per i segreti in produzione e non hard-codare mai una chiave
  • Attiva il rilevamento delle fughe nei tuoi repository Git
  • Ruota le chiavi regolarmente e revochi immediatamente qualsiasi chiave compromessa

Verifica la tua comprensione

I fondamenti dell’API xAI: un’ultima verifica prima di costruire.

1. Cosa devi fare con una chiave API non appena la crei?

Risposta: Archiviala in un luogo sicuro (viene mostrata una sola volta), esponila tramite la variabile XAI_API_KEY invece di hard-codarla, usa una chiave per ambiente e testala subito con una chiamata a /v1/models.

2. Qual è l'URL di base e perché è così importante?

Risposta: https://api.x.ai/v1. È ciò che rende possibile la compatibilità con OpenAI: cambiare base_url e la chiave è sufficiente per puntare il codice OpenAI esistente verso Grok.

3. Quali SDK puoi usare con Grok?

Risposta: L’SDK nativo xAI, l’SDK OpenAI (con il base_url di xAI) e l’SDK Vercel AI lato JavaScript, oltre a cURL per i test: l’ecosistema è aperto.

4. Qual è l'endpoint principale per la generazione?

Risposta: POST /v1/responses, il formato moderno; chat/completions rimane disponibile come opzione legacy per la compatibilità.

5. Come viene autenticata ogni richiesta?

Risposta: Con l’intestazione Authorization: Bearer e la chiave xai-…: lo schema standard Bearer token, lo stesso indipendentemente dall’SDK o dallo strumento.

Una chiave sicura, l’URL di base, la tua scelta di SDK, Bearer ovunque: le fondamenta sono poste e i prossimi corsi sull’API si baseranno su di esse.