Ověřování a efemérní tokeny
Na této stránce
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.secondsa 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ů