Autenticazione e token effimeri
In questa pagina
Due metodi di autenticazione
L’API Voice Agent offre due modalità per autenticare la tua connessione WebSocket. La scelta dipende da dove viene eseguito il tuo codice: sul server o sul client.
Chiave API diretta (lato server)
Il metodo più semplice consiste nel passare la tua chiave API nell’header di autorizzazione all’apertura del WebSocket. Questa soluzione è adatta alle applicazioni server, dove la chiave rimane protetta:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Non utilizzare mai questo metodo nel codice eseguito nel browser: la chiave API verrebbe esposta nel codice sorgente o negli strumenti di sviluppo.
Token effimeri (lato client)
Per le applicazioni front-end (browser, mobile), xAI fornisce token effimeri. Il tuo backend genera un token a breve durata di vita, che passi poi al client per aprire la connessione WebSocket.
Crei un token inviando una richiesta POST:
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": 300}}'
Il campo expires_after.seconds definisce la durata di validità del token in secondi. L’esempio nella documentazione ufficiale utilizza 300 secondi (5 minuti): un token effimero è concepito per coprire una sessione vocale, non per durare indefinitamente. Punta alla durata di vita più breve possibile compatibile con le tue sessioni.
Architettura consigliata con token effimeri
Ecco il flusso completo per un’applicazione web:
// 1. Lato server (Node.js/Express): genera il token
app.post("/api/realtime-token", 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 } })
}
);
// Restituisci il corpo della risposta di xAI così com'è;
// contiene il token effimero
res.json(await response.json());
});
// 2. Lato client (browser): usa il token
// Il costruttore WebSocket del browser non accetta header:
// il token va inserito in un SUBPROTOCOL, con il prefisso "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime",
[`xai-client-secret.${ephemeralToken}`]
);
ws.onopen = () => {
console.log("Voice session started");
};
}
Rinnovo dei token
La documentazione non specifica se un token in scadenza chiuda una connessione già aperta. In ogni caso, la tua applicazione deve prevedere una strategia per le interruzioni di connessione: monitora l’evento di chiusura, richiedi un nuovo token al tuo backend e riconnettiti:
ws.onclose = async () => {
// Connessione persa o chiusa: richiedi un nuovo token
const newToken = await fetchNewToken();
reconnect(newToken);
};
Best practice di sicurezza
Alcune regole essenziali garantiscono la sicurezza delle tue connessioni:
- Non esporre mai la tua chiave API principale sul client
- Mantieni la durata di vita (
expires_after.seconds) il più breve possibile: se la tua sessione media dura cinque minuti, 300-600 secondi sono sufficienti - Valida le richieste di token sul server (autenticazione utente, limitazione della frequenza delle richieste)
- Registra la creazione dei token per individuare utilizzi anomali
- Ruota la tua chiave API principale se sospetti che sia stata compromessa
Punti chiave
- Una chiave API diretta è adatta solo alle applicazioni server
- I token effimeri sono indispensabili per le app lato client (browser, mobile)
- Imposta la durata del token con
expires_after.secondse mantienila breve (300 secondi nell’esempio ufficiale) - Flusso consigliato: il backend genera il token e il front-end lo passa come sottoprotocollo
xai-client-secret.per aprire il WebSocket - Prevedi sempre il rinnovo automatico dei token