Ephemeral tokenek és biztonság
Ezen az oldalon
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.
Hogyan működik?
A folyamat öt lépésre redukálható:
- A backended (egy biztonságos szerver) meghívja a
POST /v1/realtime/client_secretsvégpontot az API-kulcsoddal. - Az API visszaad egy ideiglenes tokent korlátozott élettartammal.
- A backended elküldi ezt a tokent a kliensnek (böngésző vagy mobilalkalmazás).
- A kliens a tokent használja a Voice Agent WebSocket kapcsolathoz.
- 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_secretsvisszatérési értékei avalueés azexpires_at; azexpires_after.secondsalapé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