Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Ephemeral tokenek és biztonság

13. lecke 14 közül Frissítve 2026. november 3. Középhaladó
Ezen az oldalon
  1. Az API-kulcs kliens oldali használatának kockázatai
  2. Hogyan működik?
  3. A végpontok közötti architektúra
  4. Szabályok, amelyeket soha nem szeghetsz meg
  5. Főbb megállapítások

Frissítve: 2026. november 3., az xAI Voice API referenciája alapján. Források: Ephemeral Tokens · Voice API reference · Session Resumption.

Az API-kulcs kliens oldali használatának kockázatai

Egy böngészőben vagy telefonon futó hangalkalmazás nem tartalmazhatja az API-kulcsodat. Bármely látogató megnyithatja a fejlesztői eszközöket, kiolvashatja a kulcsot a JavaScript csomagból vagy egy kérés fejlécéből, majd a saját számládon használhatja azt egészen addig, amíg a kvótád ki nem merül. Semmilyen kódobfuszkáció nem véd meg egy olyan értéket, amelyre a kliensnek szüksége van az API hívásához.

Az xAI megoldása az ephemeral token (más néven kliens titok): egy rövid élettartamú token, amelyet a szervered generál, és amely kizárólag egy hangmunkamenet engedélyezésére szolgál, semmi másra.

600s
alapértelmezett élettartam
3600s
maximális élettartam
POST
/v1/realtime/client_secrets
value
a token, az expires_at értékkel

Hogyan működik?

A folyamat öt lépésre redukálható:

  1. A backended (egy biztonságos szerver) meghívja a POST /v1/realtime/client_secrets végpontot az API-kulcsoddal.
  2. Az API visszaad egy ideiglenes tokent korlátozott élettartammal.
  3. A backended elküldi ezt a tokent a kliensnek (böngésző vagy mobilalkalmazás).
  4. A kliens a tokent használja a Voice Agent WebSocket kapcsolathoz.
  5. A token lejár a választott élettartam (expires_after.seconds) végén.

Ami így a kliens oldalon esetleg kiszivárog, az sokkal kevesebbet ér: egy olyan token, amely percek alatt elévül, és csak egy hangmunkamenet megnyitására alkalmas, nem pedig az API-kulcsodra. A szerveren a generálás néhány sor kódot igényel. Figyeld meg, hogy a kezelőrutin a felhasználó ellenőrzésével kezdődik: e nélkül a backended csupán egy nyilvános tokenosztó gép lenne.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Ellenőrizd, hogy a felhasználó hitelesítve van-e
  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 perc, az alapértelmezett érték
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

A kliens csak a saját útvonaladat ismeri: kér egy tokent, majd ezzel nyitja meg a WebSocket kapcsolatot.

// Frontend (böngésző)
async function startVoiceSession() {
  // Token kérése a backendtől
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // A böngésző WebSocket nem fogad el fejléceket:
  // a token egy alprotokollba kerül, "xai-client-secret." előtaggal.
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... munkamenet konfiguráció
}

A végpontok közötti architektúra

Összegezve: a folyamat a felhasználó alkalmazásba való bejelentkezésével indul. A kliens ezután hangtokent kér a backendedtől, a backend pedig ellenőrzi a hitelesítést és a jogosultságokat, mielőtt az xAI API-n keresztül generálná az ephemeral tokent. A token visszakerül a klienshez, amely ezzel nyitja meg a Voice Agent munkamenetet, és az automatikusan lejár az élettartama végén.

Ez az ellenőrzés a kérés és a generálás között egyszerű továbbítóból ellenőrző pontot csinál, és itt élnek az üzleti szabályaid. Korlátozhatod a felhasználónkénti napi hangmunkamenetek számát, így egyetlen fiók sem égetheti fel egy éjszaka alatt a havi költségkeretedet. Fenntarthatsz tokeneket az aktív előfizetések számára, ezzel az üzleti modellt nem a felületen, hanem máshol érvényesítve. Korlátozhatod a kérések számát (rate-limiting), hogy egy hibás vagy rosszindulatú kliens ne kérhessen le ezer tokent percenként. És naplózhatod az összes generált tokent: ez az egyetlen megbízható alapod a monitorozáshoz, a belső számlázáshoz és az incidenselemzéshez.

Szabályok, amelyeket soha nem szeghetsz meg

Az API-kulcs soha, semmilyen formában nem kerülhet a kliensre. Tartsd távol a front-end JavaScripttől és minden olyan környezeti változótól, amely a böngésző build folyamatának ki van téve (a csomagba injektálásra előkészített változók végül nyilvánossá válnak). Tartsd távol az URL-ektől, a naplófájloktól és a felhasználóknak megjelenített hibaüzenetektől is.

Másodszor: tartsd az élettartamot a lehető legrövidebbre, amennyire gyakorlatias. Az API referencia szerint az expires_after.seconds alapértelmezett értéke 600 másodperc, maximuma pedig 3600; a dokumentáció példái 300-at használnak. Mindenekfelett: a tokennek érvényesnek kell lennie, amikor a kliens megnyitja a kapcsolatot. A rövid élettartam csökkenti azt az időablakot, amely alatt egy elfogott token felhasználható.

A dokumentáció nem tisztázza, hogy egy lejáró token megszakítja-e a már nyitva lévő kapcsolatot. Ha a kliensnek újra kell kapcsolódnia (hálózati kimaradás után vagy nagyon hosszú munkamenet során), kérj egy új tokent, és használd a munkamenet-folytatást (session resumption): engedélyezd a resumption.enabled opciót a session.update üzenetben, őrizd meg a conversation.created eseményben kapott azonosítót, majd nyisd meg újra a WebSocketet a ?conversation_id=<id> paraméterrel. A korábbi fordulók lejátszásra kerülnek, és a modell ott folytatja, ahol abbahagyta.

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 } },  // minden kapcsolódáskor elküldendő
  }));
  return ws;
}

HTTP módú TTS (szövegfelolvasás) esetén van egy még egyszerűbb alternatíva a tokenek helyett: a proxy. A kliens elküldi a szöveget a backendednek, a backended hívja meg a TTS szolgáltatást, és visszaadja a hangfájlt. A kulcs soha nem hagyja el a szerveredet, és természetes lehetőséget kapsz a tartalom szűrésére és a használat mérésére menet közben.

Főbb megállapítások

  • Az ephemeral tokenek biztosítják a Voice Agent hozzáférését a kliens oldali alkalmazásokból
  • A POST /v1/realtime/client_secrets visszatérési értékei a value és az expires_at; az expires_after.seconds alapértelmezett értéke 600, maximuma 3600
  • Böngészőben a token az xai-client-secret.<token> alprotokollba kerül
  • A backendednek ellenőriznie kell a hitelesítést és a jogosultságokat token generálása előtt
  • Soha ne tedd közzé az API-kulcsodat a kliensen, URL-ekben vagy naplókban
  • HTTP alapú TTS esetén a backenden keresztüli proxyzás érvényes alternatíva az ephemeral tokenekkel szemben