Token effimeri per le connessioni WebSocket
In questa pagina
Il problema: autenticare un client senza esporre la tua chiave
Quando sviluppi un’app vocale o in tempo reale con le API di Grok, devi stabilire una connessione WebSocket direttamente dal browser o dal client mobile. Instradare il traffico attraverso il tuo server aggiunge latenza, rompendo la fluidità della conversazione vocale. Tuttavia, le connessioni dirette creano un problema di autenticazione: non devi mai includere la tua chiave API nel codice lato client.
La ragione è semplice: qualsiasi chiave incorporata in JavaScript frontend, in un’app mobile decompilabile o in un binario distribuito viene compromessa nel momento stesso in cui la pubblichi. Qualsiasi utente può aprire gli strumenti di sviluppo del browser e leggerla. Per risolvere questo problema, xAI offre i token effimeri: token temporanei che i client possono utilizzare senza mai vedere la chiave master.
Come funzionano i token effimeri
L’architettura segue un principio fondamentale: la chiave API non lascia mai il tuo server e il client riceve solo un token a breve durata. Il flusso è breve. Il client richiede un token al tuo backend, che chiama POST /v1/realtime/client_secrets utilizzando la tua chiave API. Questa chiamata è l’unico punto in cui appare la chiave e avviene interamente lato server. xAI restituisce un token effimero con la sua data di scadenza, che il tuo backend passa al client. Il client apre quindi la connessione WebSocket a wss://api.x.ai/v1/realtime presentando questo token. In nessun momento il browser vede la chiave master; gestisce solo un token che scade automaticamente.
La chiamata di creazione dal tuo backend appare così:
curl -X POST https://api.x.ai/v1/realtime/client_secrets \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_after": {"seconds": 600}}'
E la risposta:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Per quanto riguarda la durata, hai tre punti di riferimento: non esiste un limite inferiore documentato (sono possibili pochi secondi), il valore predefinito è di 600 secondi (10 minuti) e il massimo è di 3600 secondi (1 ora).
Scegliere la durata giusta
La durata del token deve corrispondere al tuo caso d’uso; questa scelta rappresenta una vera decisione di sicurezza. Per interazioni vocali sporadiche—domande e risposte, comandi vocali, dettatura—una finestra da 300 a 600 secondi è più che sufficiente: la sessione terminerà ben prima della scadenza. Per conversazioni vocali prolungate come il supporto clienti, un colloquio o una riunione assistita, punta a 600-1800 secondi per evitare interruzioni a metà conversazione. Sessioni di lavoro lunghe—trascrizione in tempo reale, monitoraggio vocale continuo—possono giustificare 1800-3600 secondi, ma usa la durata massima con cautela: espande la finestra di sfruttamento se il token viene rubato.
La regola d’oro si riassume così: scegli sempre la durata più breve compatibile con il tuo caso d’uso. Se un token viene intercettato, una scadenza di dieci minuti trasforma un potenziale incidente grave in un semplice fastidio.
Implementazione backend
Ecco un esempio di proxy sicuro in Node.js:
// Rotta backend - NON esporre lato client
app.post("/api/realtime-token", authenticateUser, async (req, res) => {
const response = await fetch(
"https://api.x.ai/v1/realtime/client_secrets",
{
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
expires_after: { seconds: 600 }
})
}
);
const token = await response.json();
res.json({ token: token.value, expires_at: token.expires_at });
});
Tre dettagli in questo esempio reggono l’intera sicurezza dell’implementazione. La chiave API risiede in una variabile d’ambiente del server, mai nel codice. Il middleware authenticateUser verifica l’identità dell’utente prima di rilasciare un token—senza di esso, chiunque potrebbe ottenere token e consumare la tua quota a tue spese. Infine, solo il token effimero, mai la chiave, viene restituito al client.
Alcuni errori ricorrono spesso nelle revisioni del codice. La chiave API inserita nel frontend “solo per il prototipo” finisce inevitabilmente in produzione. Il token creato sistematicamente con la durata massima, per comodità, quando il caso d’uso ne richiede un quarto. L’endpoint di generazione lasciato senza verifica dell’autenticazione, aperto a tutti. E la mancanza di gestione del rinnovo lato client, che genera errori di scadenza a metà sessione invece di una riconnessione trasparente: poiché la risposta ti fornisce expires_at, il tuo client ha tutto il necessario per richiedere un nuovo token prima della scadenza, non dopo.
Punti chiave
- I token effimeri abilitano l’autenticazione WebSocket senza esporre la tua chiave API
- Endpoint:
POST /v1/realtime/client_secrets(chiamata esclusivamente lato server) - Durata configurabile da pochi secondi fino a un massimo di 3600 secondi (predefinito: 600s)
- Il tuo backend agisce come un proxy di autenticazione tra il client e xAI
- Scegli sempre la durata più breve compatibile con il tuo utilizzo