Autenticazione con token Bearer
In questa pagina
Metti in sicurezza le tue chiamate API
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_KEYsia 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:
- Crea una nuova chiave nella console xAI
- Aggiorna la chiave nel tuo vault per i segreti
- Ridistribuisci la tua applicazione
- Verifica che tutto funzioni con la nuova chiave
- 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:
- Revochila immediatamente nella console xAI
- Controlla la tua cronologia d’uso per individuare utilizzi fraudolenti
- Crea una nuova chiave
- 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.