Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Overovanie a prechodné tokeny

Lekcia 2 z 16 Aktualizované 30. júla 2026 Vývojár
Na tejto strane
  1. Dva spôsoby overenia
  2. Odporúčaná architektúra s prechodnými tokenmi
  3. Najlepšie postupy zabezpečenia
  4. Kľúčové poznatky

Dva spôsoby overenia

API Voice Agent ponúka dva spôsoby overenia vášho WebSocket pripojenia. Výber závisí od toho, kde beží váš kód: na serveri alebo na strane klienta.

Priamy API kľúč (serverová strana)

Najjednoduchšou metódou je odovzdanie vášho API kľúča v hlavičke authorization pri otváraní WebSocketu. Toto funguje pre serverové aplikácie, kde zostáva kľúč chránený:

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

Túto metódu nikdy nepoužívajte v kóde, ktorý beží v prehliadači: API kľúč by sa odhalil v zdrojovom kóde alebo vo vývojárskych nástrojoch.

Prechodné tokeny (klientská strana)

Pre front-endové aplikácie (prehliadač, mobilné zariadenia) poskytuje xAI prechodné tokeny. Váš backend vygeneruje krátkodobý token, ktorý následne odovzdáte klientovi na otvorenie WebSocket pripojenia.

Token vytvoríte pomocou požiadavky 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}}'

Pole expires_after.seconds určuje, ako dlho je token platný, v sekundách. Príklad v oficiálnej dokumentácii používa 300 sekúnd (5 minút): prechodný token má pokryť hlasovú reláciu, nie trvať večne. Snažte sa nastaviť čo najkratšiu životnosť, ktorá vyhovuje vašim reláciám.

Odporúčaná architektúra s prechodnými tokenmi

Tu je kompletný tok pre webovú aplikáciu:

// 1. Serverová strana (Node.js/Express): vygenerovanie tokenu
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 } })
    }
  );
  // Vrátite telo odpovede xAI tak, ako je;
  // obsahuje prechodný token
  res.json(await response.json());
});

// 2. Klientská strana (prehliadač): použitie tokenu
// Konštruktor WebSocket v prehliadači neprijíma hlavičky:
// token sa odovzdáva v SUBPROTOCOL s predponou "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");
  };
}

Obnova tokenov

Dokumentácia nešpecifikuje, či expirujúci token uzavrie už otvorené pripojenie. V každom prípade potrebuje vaša aplikácia plán pre prípad vypadnutia pripojenia: sledujte udalosť uzavretia, požiadajte backend o nový token a potom sa znovu pripojte:

ws.onclose = async () => {
  // Pripojenie stratené alebo uzavreté: vyžiadať nový token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Najlepšie postupy zabezpečenia

Niekoľko zásadných pravidiel udrží vaše pripojenia v bezpečí:

  • Nikdy neodhaľujte svoj hlavný API kľúč na strane klienta
  • Udržujte životnosť (expires_after.seconds) čo najkratšiu: ak vaša priemerná relácia trvá päť minút, stačí 300 až 600 sekúnd
  • Overujte požiadavky na tokeny na serveri (overenie používateľa, obmedzenie rýchlosti)
  • Logujte vytváranie tokenov, aby ste odhalili abnormálne využitie
  • Rotujte svoj hlavný API kľúč, ak máte podozrenie na jeho kompromitáciu

Kľúčové poznatky

  • Priamy API kľúč je vhodný len pre serverové aplikácie
  • Prechodné tokeny sú nevyhnutnosťou pre klientské aplikácie (prehliadač, mobilné zariadenia)
  • Životnosť tokenu nastavte pomocou expires_after.seconds a udržujte ju krátku (v oficiálnom príklade 300 sekúnd)
  • Odporúčaný tok: váš backend vygeneruje token a váš front-end ho odovzdá ako subprotokol xai-client-secret. na otvorenie WebSocketu
  • Vždy plánujte automatickú obnovu tokenov