Jetoane efemere și securitate
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza referinței API Voice de la xAI. Surse: Jetoane Efemere · Referință API Voice · Reluarea Sesiunii.
Problema cheii API pe partea clientului
O aplicație vocală care rulează într-un browser sau pe un telefon nu poate include cheia dumneavoastră API. Orice vizitator poate deschide instrumentele pentru dezvoltatori, poate citi cheia din pachetul JavaScript sau dintr-un antet de cerere și o poate utiliza în contul dumneavoastră până când cota se epuizează. Nicio cantitate de obscurizare nu protejează o valoare pe care clientul trebuie să o dețină pentru a apela API-ul.
Răspunsul xAI îl constituie jetoanele efemere, numite și secrete de client: un jeton cu durată scurtă de viață, generat de serverul dumneavoastră, care autorizează o sesiune vocală și nimic altceva.
Cum funcționează
Fluxul se rezumă la cinci pași:
- Backend-ul dumneavoastră (un server securizat) apelează
POST /v1/realtime/client_secretscu cheia dumneavoastră API - API-ul returnează un jeton temporar cu o durată de viață limitată
- Backend-ul dumneavoastră trimite acel jeton către client (browser sau aplicație mobilă)
- Clientul utilizează jetonul pentru a se conecta la WebSocket-ul Agentului Voice
- Jetonul expiră după durata de viață aleasă de dumneavoastră (
expires_after.seconds)
Ceea ce poate fi compromis pe partea clientului valorează acum mult mai puțin: un jeton care expiră în câteva minute și poate deschide doar o sesiune vocală, nu cheia dumneavoastră API. Pe server, generarea unui astfel de jeton necesită câteva linii de cod. Observați că handler-ul începe prin verificarea utilizatorului: fără acea verificare, backend-ul dumneavoastră devine doar un distribuitor public de jetoane.
// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
// Verificați dacă utilizatorul este autentificat
if (!req.user) return res.status(401).json({ error: "Unauthorized" });
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 } // 10 minute, valoarea implicită
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Clientul cunoaște doar ruta dumneavoastră proprie: solicită un jeton, apoi deschide WebSocket-ul cu acesta.
// Frontend (browser)
async function startVoiceSession() {
// Solicitați un jeton de la backend
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// WebSocket-ul din browser nu acceptă antete:
// jetonul merge într-un subprotocol, prefixat cu "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... configurarea sesiunii
}
Arhitectura end-to-end
Privind ansamblul, fluxul începe cu autentificarea utilizatorului în aplicația dumneavoastră. Clientul său solicită apoi backend-ului dumneavoastră un jeton vocal, iar backend-ul verifică autentificarea și permisiunile înainte de a genera jetonul efemer prin API-ul xAI. Jetonul călătorește înapoi către client, care îl utilizează pentru a deschide sesiunea Agentului Voice, expirând automat la sfârșitul duratei sale de viață.
Această verificare între cerere și generare transformă un simplu releu într-un punct de control, iar aici rezidă regulile dumneavoastră de afaceri. Puteți limita numărul de sesiuni vocale per utilizator pe zi, astfel încât un singur cont să nu poată epuiza bugetul lunar peste noapte. Puteți rezerva jetoane pentru abonamente active, impunând modelul de afaceri în altă parte decât la interfață. Puteți limita rata cererilor, astfel încât un client defect sau rău intenționat să nu poată solicita o mie de jetoane pe minut. Și puteți înregistra fiecare jeton generat: aceasta este singura bază fiabilă pentru monitorizare, facturare internă și analiza incidentelor.
Reguli pe care nu trebuie să le încălcați niciodată
Cheia API nu ajunge niciodată la client, sub nicio formă. Țineți-o departe de JavaScript-ul din front-end și departe de orice variabilă de mediu expusă compilării pentru browser (variabilele prefixate pentru a fi injectate în pachet devin publice). Țineți-o departe și de URL-uri, jurnale (logs) și mesaje de eroare afișate utilizatorilor.
În continuare, mențineți durata de viață cât mai scurtă posibil, în limitele practicii. Conform referinței API, expires_after.seconds are implicit 600 de secunde și o valoare maximă de 3.600; documentația utilizează 300 în exemplele sale. Mai presus de toate, jetonul trebuie să fie valid atunci când clientul deschide conexiunea. O durată de viață scurtă reduce fereastra de timp în care un jeton interceptat poate fi utilizat.
Documentația nu specifică dacă un jeton care expiră întrerupe o conexiune deja deschisă. Dacă clientul dumneavoastră trebuie să se reconecteze, după o întrerupere de rețea sau în timpul unei sesiuni foarte lungi, solicitați un nou jeton și utilizați reluarea sesiunii: activați resumption.enabled în session.update, păstrați ID-ul primit în conversation.created, apoi redeschideți WebSocket-ul cu ?conversation_id=<id>. Schimburile anterioare sunt redate, iar modelul continuă de unde a rămas.
async function reconnect(conversationId) {
const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
ws.onopen = () => ws.send(JSON.stringify({
type: "session.update",
session: { resumption: { enabled: true } }, // trimite din nou la fiecare conexiune
}));
return ws;
}
Pentru TTS în mod HTTP, există o alternativă și mai simplă la jetoane: un proxy. Clientul trimite textul către backend-ul dumneavoastră, iar backend-ul apelează TTS și returnează audio-ul. Cheia nu părăsește niciodată serverul dumneavoastră, iar dumneavoastră obțineți un loc natural pentru a filtra conținutul și a măsura utilizarea în acest proces.
Puncte cheie
- Jetoanele efemere securizează accesul la Agentul Voice din aplicațiile lato-client
POST /v1/realtime/client_secretsreturneazăvalueșiexpires_at;expires_after.secondsare implicit 600 și o valoare maximă de 3.600- În browser, jetonul merge în subprotocolul
xai-client-secret.<token> - Backend-ul dumneavoastră trebuie să verifice autentificarea și permisiunile înainte de a genera un jeton
- Nu expuneți niciodată cheia API pe client, în URL-uri sau în jurnale
- Pentru TTS HTTP, utilizarea unui proxy prin backend-ul dumneavoastră este o alternativă validă la jetoanele efemere