Salt la conținutul principal
Română— Alege o limbă
Meniu

Jetoane efemere pentru conexiuni WebSocket

Lecția 5 din 12 Actualizată 28 iulie 2026 Avansat
Pe această pagină
  1. Problema: autentificarea unui client fără a expune cheia dumneavoastră
  2. Cum funcționează jetoanele efemere
  3. Alegerea duratei potrivite
  4. Implementare lato-server
  5. Puncte cheie

Problema: autentificarea unui client fără a expune cheia dumneavoastră

Atunci când construiți o aplicație vocală sau în timp real cu API-ul Grok, trebuie să stabiliți o conexiune WebSocket direct din browser sau de pe clientul mobil. Redirecționarea traficului prin serverul dumneavoastră adaugă latență, ceea ce perturbă conversația vocală fluidă. Însă conexiunile directe creează o problemă de autentificare: nu trebuie niciodată să includeți cheia API în codul lato-client.

Motivul este simplu: orice cheie încorporată în JavaScript-ul din frontend, într-o aplicație mobilă decompilabilă sau într-un binar distribuit este compromisă în momentul publicării. Orice utilizator își poate deschide instrumentele de dezvoltare ale browserului și o poate citi. Pentru a rezolva această problemă, xAI oferă jetoane efemere: jetoane temporare pe care clienții le pot utiliza fără a vedea vreodată cheia principală.

600s
Durată implicită
3600s
Durată maximă
POST
/v1/realtime/client_secrets
Bearer
Jeton temporar

Cum funcționează jetoanele efemere

Arhitectura se bazează pe un singur principiu: cheia API nu părăsește niciodată serverul dumneavoastră, iar clientul primește doar un jeton cu durată scurtă de viață. Fluxul este scurt. Clientul solicită un jeton backend-ului dumneavoastră, care apelează POST /v1/realtime/client_secrets cu cheia API. Acest apel este singurul loc unde apare cheia și se întâmplă exclusiv lato-server. xAI returnează un jeton efemer împreună cu data de expirare, pe care backend-ul dumneavoastră îl transmite clientului. Clientul deschide apoi conexiunea WebSocket la wss://api.x.ai/v1/realtime prezentând acest jeton. În niciun moment browserul nu vede cheia principală; acesta gestionează un jeton care expiră automat.

Apelul de creare din backend arată astfel:

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}}'

Și răspunsul:

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

În ceea ce privește durata, aveți trei repere: nu există un prag minim documentat (sunt posibile câteva secunde), valoarea implicită este de 600 de secunde (10 minute), iar maximul este de 3600 de secunde (1 oră).

Alegerea duratei potrivite

Durata jetonului trebuie să corespundă cazului dumneavoastră de utilizare, iar această alegere reprezintă o decizie reală de securitate. Pentru interacțiuni vocale sporadice—un Q&A, o comandă vocală, dictare—o fereastră de 300 până la 600 de secunde este suficientă: sesiunea se va încheia cu mult înainte de expirare. Pentru conversații vocale susținute, cum ar fi suportul pentru clienți, un interviu sau o ședință asistată, vizați 600 până la 1800 de secunde pentru a evita întreruperea conversației. Sesiunile de lucru prelungite—transcriere în timp real, monitorizare vocală continuă—pot justifica 1800 până la 3600 de secunde, dar utilizați durata maximă cu prudență: aceasta extinde fereastra de exploatare dacă jetonul este furat.

Regula de aur se rezumă astfel: alegeți întotdeauna cea mai scurtă durată compatibilă cu cazul dumneavoastră de utilizare. Dacă un jeton este interceptat, o expirare după zece minute transformă un incident potențial grav într-o simplă neplăcere minoră.

Implementare lato-server

Iată un exemplu de proxy securizat în Node.js:

// Rută backend - A NU SE expune 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 });
});

Trei detalii din acest exemplu susțin întreaga securitate a configurării. Cheia API se află într-o variabilă de mediu lato-server, niciodată în cod. Middleware-ul authenticateUser verifică identitatea utilizatorului înainte de a emite un jeton—fără acesta, oricine ar putea obține jetoane și consuma cota dumneavoastră pe cheltuiala dumneavoastră. Și doar jetonul efemer, niciodată cheia, este returnat clientului.

Câteva capcane apar regulat în revizuirile de cod. Cheia API strecurată în frontend „doar pentru prototip“ ajunge invariabil în producție. Jetonul creat sistematic cu durata maximă, pentru comoditate, atunci când cazul de utilizare necesită un sfert din aceasta. Endpoint-ul de generare lăsat fără verificare de autentificare, deschis tuturor. Și lipsa gestionării reînnoirii lato-client, care produce erori de expirare în mijlocul sesiunii în loc de o reconectare transparentă: deoarece răspunsul vă oferă expires_at, clientul dumneavoastră are tot ce îi trebuie pentru a solicita un nou jeton înainte de termenul limită, nu după.

Puncte cheie

  • Jetoanele efemere permit autentificarea WebSocket fără a expune cheia API
  • Endpoint: POST /v1/realtime/client_secrets (apel exclusiv lato-server)
  • Durată configurabilă de la câteva secunde până la maximum 3600 de secunde (implicit: 600s)
  • Backend-ul dumneavoastră acționează ca un proxy de autentificare între client și xAI
  • Alegeți întotdeauna durata cea mai scurtă compatibilă cu utilizarea dumneavoastră