Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Ověřování a efemérní tokeny

Lekce 2 z 16 Aktualizováno 30. července 2026 Vývojář
Na této stránce
  1. Dva způsoby ověření
  2. Doporučená architektura s efemérními tokeny
  3. Osvědčené postupy zabezpečení
  4. Klíčové poznatky

Dva způsoby ověření

API Voice Agent nabízí dva způsoby ověření vašeho WebSocket připojení. Který zvolíte, závisí na tom, kde váš kód běží: na serveru, nebo na straně klienta.

Přímý API klíč (serverová strana)

Nejjednodušší metodou je předat váš API klíč v hlavičce authorization při otevírání WebSocketu. Toto funguje pro serverové aplikace, kde zůstává klíč chráněn:

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

Tuto metodu nikdy nepoužívejte v kódu, který běží v prohlížeči: API klíč by byl odhalen ve zdrojovém kódu nebo v nástrojích pro vývojáře.

Efemérní tokeny (klientská strana)

Pro front-endové aplikace (prohlížeč, mobilní zařízení) poskytuje xAI efemérní tokeny. Váš backend vygeneruje krátkodobý token, který následně předáte klientovi k otevření WebSocket připojení.

Token vytvoříte pomocí požadavku 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, jak dlouho je token platný, v sekundách. Příklad v oficiální dokumentaci používá 300 sekund (5 minut): efemérní token je určen k pokrytí hlasové relace, nikoliv k dlouhodobému používání. Usilujte o co nejkratší dobu životnosti, která pro vaše relace stačí.

Doporučená architektura s efemérními tokeny

Zde je kompletní tok pro webovou aplikaci:

// 1. Serverová strana (Node.js/Express): vygenerování 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átíme tělo odpovědi xAI tak, jak je;
  // obsahuje efemérní token
  res.json(await response.json());
});

// 2. Klientská strana (prohlížeč): použití tokenu
// Konstruktor WebSocketu v prohlížeči nepřijímá hlavičky:
// token se předá jako SUBPROTOCOL s prefixem "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 tokenů

Dokumentace neupřesňuje, zda expirující token uzavře již otevřené připojení. V každém případě musí vaše aplikace mít plán pro případ přerušení spojení: sledujte událost uzavření, vyžádejte si od backendu nový token a znovu se připojte:

ws.onclose = async () => {
  // Připojení ztraceno nebo uzavřeno: vyžádat nový token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Osvědčené postupy zabezpečení

Několik zásadních pravidel udrží vaše připojení v bezpečí:

  • Nikdy neodhalujte svůj hlavní API klíč na straně klienta
  • Udržujte dobu životnosti (expires_after.seconds) co nejkratší: pokud vaše průměrná relace trvá pět minut, stačí 300 až 600 sekund
  • Ověřujte požadavky na tokeny na serveru (ověření uživatele, omezování rychlosti požadavků)
  • Protokolujte vytváření tokenů, abyste odhalili neobvyklé využití
  • Obměňte svůj hlavní API klíč, pokud máte podezření na jeho kompromitaci

Klíčové poznatky

  • Přímý API klíč je vhodný pouze pro serverové aplikace
  • Efemérní tokeny jsou nezbytností pro klientské aplikace (prohlížeč, mobilní zařízení)
  • Doba životnosti tokenu se nastavuje pomocí expires_after.seconds a měla by být krátká (v oficiálním příkladu 300 sekund)
  • Doporučený tok: váš backend vygeneruje token a váš front-end jej předá jako subprotokol xai-client-secret. k otevření WebSocketu
  • Vždy plánujte automatickou obnovu tokenů