Autentificare și token-uri efemere
Pe această pagină
Două modalități de autentificare
API-ul Voice Agent oferă două metode pentru a autentifica conexiunea dumneavoastră WebSocket. Alegerea metodei depinde de locul în care rulează codul: pe server sau pe client.
Cheie API directă (lato server)
Cea mai simplă metodă constă în transmiterea cheii API în antetul de autorizare la deschiderea conexiunii WebSocket. Această abordare este potrivită pentru aplicațiile server, unde cheia rămâne protejată:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Nu utilizați niciodată această metodă în codul care rulează în browser: cheia API ar fi expusă în codul sursă sau în instrumentele pentru dezvoltatori.
Token-uri efemere (lato client)
Pentru aplicațiile front-end (browser, mobile), xAI pune la dispoziție token-uri efemere. Backend-ul dumneavoastră generează un token cu durată scurtă de viață, pe care îl transmiteți apoi clientului pentru a deschide conexiunea WebSocket.
Creați un token prin intermediul unei cereri 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}}'
Câmpul expires_after.seconds stabilește durata de valabilitate a token-ului, în secunde. Exemplul din documentația oficială utilizează 300 de secunde (5 minute): un token efemer este conceput pentru a acoperi o sesiune vocală, nu pentru a persista. Vizați cea mai scurtă durată de viață posibilă care funcționează pentru sesiunile dumneavoastră.
Arhitectură recomandată cu token-uri efemere
Iată fluxul complet pentru o aplicație web:
// 1. Lato server (Node.js/Express): generarea token-ului
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 } })
}
);
// Returnați corpul răspunsului xAI așa cum este;
// acesta conține token-ul efemer
res.json(await response.json());
});
// 2. Lato client (browser): utilizarea token-ului
// Constructorul WebSocket din browser nu acceptă anteturi:
// token-ul se transmite într-un SUBPROTOCOL, cu prefixul "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");
};
}
Reînnoirea token-urilor
Documentația nu specifică dacă un token care expiră închide o conexiune deja deschisă. Indiferent de situație, aplicația dumneavoastră trebuie să aibă un plan pentru momentul în care conexiunea se întrerupe: monitorizați evenimentul de închidere, solicitați un nou token backend-ului și reconectați-vă:
ws.onclose = async () => {
// Conexiune pierdută sau închisă: solicitați un nou token
const newToken = await fetchNewToken();
reconnect(newToken);
};
Cele mai bune practici de securitate
Câteva reguli esențiale vă mențin conexiunile în siguranță:
- Nu expuneți niciodată cheia API principală pe partea client
- Mențineți durata de viață (
expires_after.seconds) cât mai scurtă posibil: dacă sesiunea medie durează cinci minute, 300 până la 600 de secunde sunt suficiente - Validați cererile de token pe server (autentificarea utilizatorului, limitarea ratei de cereri)
- Jurnalizați crearea token-urilor pentru a detecta utilizări anormale
- Rotați cheia API principală dacă suspectați că a fost compromisă
Puncte cheie
- O cheie API directă este potrivită doar pentru aplicațiile server
- Token-urile efemere sunt obligatorii pentru aplicațiile lato client (browser, mobile)
- Stabiliți durata de viață a token-ului cu
expires_after.secondsși mențineți-o scurtă (300 de secunde în exemplul oficial) - Fluxul recomandat: backend-ul generează token-ul, iar front-end-ul îl transmite ca subprotocol
xai-client-secret.pentru a deschide WebSocket-ul - Planificați întotdeauna reînnoirea automată a token-urilor