Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Autentimine ja ajutised tokenid

Õppetund 2 / 16 Värskendatud 30. juuli 2026 Arendajatele
Sellel lehel
  1. Kaks autentimisviisi
  2. Soovitatav arhitektuur ajutiste tokenitega
  3. Turvalisuse parimad tavad
  4. Peamised punktid

Kaks autentimisviisi

Voice Agent API pakub WebSocketi ühenduse autentimiseks kahte viisi. Valik sõltub sellest, kus sinu kood töötab: serveris või kliendil.

Otsene API-võti (serveripoolne)

Lihtsaim meetod on edastada oma API-võti autoriseerimispäises WebSocketi avamisel. See sobib serverirakendustele, kus võti jääb kaitstuks:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Ära kunagi kasuta seda meetodit koodis, mis töötab brauseris: API-võti paljastuks lähtekoodis või arendaja tööriistades.

Ajutised tokenid (kliendipoolne)

Rakenduste jaoks, mis töötavad kasutaja seadmes (brauser, mobiil), pakub xAI ajutisi tokeneid. Sinu tagarakendus genereerib lühiajalise tokeni, mille edastad kliendile WebSocketi ühenduse loomiseks.

Tokeni loomiseks saadad POST-päringu:

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

Väli expires_after.seconds määrab, kui kaua token kehtib (sekundites). Ametlikus dokumentatsioonis toodud näites on kasutatud 300 sekundit (5 minutit): ajutine token on mõeldud katma ühte kõneseanssi, mitte kestma igavesti. Püüa valida oma seansside jaoks võimalikult lühike kehtivusaeg.

Soovitatav arhitektuur ajutiste tokenitega

Siin on veebirakenduse täielik töövoog:

// 1. Serveripoolne (Node.js/Express): tokeni genereerimine
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 } })
    }
  );
  // Tagasta xAI vastuse keha muutumatuna;
  // see sisaldab ajutist tokenit
  res.json(await response.json());
});

// 2. Kliendipoolne (brauser): tokeni kasutamine
// Brauseri WebSocketi konstruktor ei aktsepteeri päiseid:
// token edastatakse ALAMPROTOKOLLIS, eesliitega "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");
  };
}

Tokenite uuendamine

Dokumentatsioonis ei ole täpsustatud, kas aeguva tokeni korral suletakse juba avatud ühendus. Igaks juhuks peab sinu rakendusel olema plaan ühenduse katkemiseks: jälgi sulgemissündmust, küsi tagarakenduselt uus token ja loo ühendus uuesti:

ws.onclose = async () => {
  // Ühendus katkes või suleti: küsi uus token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Turvalisuse parimad tavad

Mõned olulised reeglid hoiavad sinu ühendused turvalisena:

  • Ära kunagi avalda oma peamist API-võtit kliendil
  • Hoia kehtivusaeg (expires_after.seconds) võimalikult lühike: kui sinu keskmine seanss kestab viis minutit, piisab 300–600 sekundist
  • Kontrolli tokenipäringuid serveris (kasutaja autentimine, kiiruse piiramine)
  • Logi tokenite loomine, et tuvastada ebanormaalset kasutust
  • Vaheta oma peamine API-võti, kui kahtlustad selle kompromiteerimist

Peamised punktid

  • Otsene API-võti sobib ainult serverirakendustele
  • Ajutised tokenid on kliendipoolsete rakenduste (brauser, mobiil) jaoks hädavajalikud
  • Määra tokeni kehtivusaeg väljaga expires_after.seconds ja hoia see lühike (ametlikus näites 300 sekundit)
  • Soovitatav töövoog: sinu tagarakendus genereerib tokeni ja sinu esirakendus edastab selle WebSocketi avamisel alamprotokollina xai-client-secret.
  • Planeeri alati tokenite automaatne uuendamine