Efemérní tokeny pro připojení WebSocket
Na této stránce
Problém: ověření klienta bez prozrazení klíče
Když vytváříš hlasovou aplikaci nebo aplikaci v reálném čase s API Grok, musíš navázat připojení WebSocket přímo z prohlížeče nebo mobilního klienta. Směrování provozu přes tvůj server přidává latenci, která narušuje plynulost hlasové konverzace. Přímá připojení však vytvářejí problém s ověřováním: nikdy nesmíš vkládat svůj API klíč do kódu na straně klienta.
Důvod je prostý: jakýkoli klíč vložený do frontendového JavaScriptu, dekompilovatelné mobilní aplikace nebo distribuovaného binárního souboru je kompromitován v okamžiku jeho publikování. Jakýkoli uživatel může otevřít vývojářské nástroje prohlížeče a přečíst si ho. Abychom to vyřešili, nabízí xAI efemérní tokeny: dočasné tokeny, které mohou klienti používat, aniž by kdy viděli hlavní klíč.
Jak fungují efemérní tokeny
Architektura vychází z jednoho principu: API klíč nikdy neopustí tvůj server a klient obdrží pouze token s krátkou dobou platnosti. Tok je stručný. Klient si vyžádá token od tvého backendu, který zavolá POST /v1/realtime/client_secrets s tvým API klíčem. Toto volání je jediným místem, kde se klíč objeví, a probíhá výhradně na straně serveru. xAI vrátí efemérní token s datem vypršení platnosti, který tvůj backend předá klientovi. Klient poté otevře připojení WebSocket na wss://api.x.ai/v1/realtime a předloží tento token. Prohlížeč hlavní klíč nikdy neuvidí; pracuje pouze s tokenem, který sám vyprší.
Volání pro vytvoření z tvého backendu vypadá takto:
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": 600}}'
A odpověď:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Pokud jde o dobu platnosti, máš tři orientační body: není zdokumentováno žádné minimum (možné jsou i několik sekund), výchozí hodnota je 600 sekund (10 minut) a maximum je 3600 sekund (1 hodina).
Volba správné doby platnosti
Doba platnosti tokenu musí odpovídat tvému případu použití a tato volba je skutečným bezpečnostním rozhodnutím. Pro sporadické hlasové interakce – otázka a odpověď, hlasový příkaz, diktování – je okno 300 až 600 sekund více než dostatečné: relace skončí dlouho před vypršením platnosti. Pro dlouhodobé hlasové konverzace, jako je zákaznická podpora, pohovor nebo asistovaná schůzka, cíli na 600 až 1800 sekund, abys předešel přerušení uprostřed hovoru. Dlouhé pracovní relace – přepis v reálném čase, nepřetržité hlasové monitorování – mohou ospravedlnit 1800 až 3600 sekund, ale maximální dobu platnosti používej opatrně: rozšiřuje okno pro zneužití, pokud je token ukraden.
Zlaté pravidlo zní takto: vždy zvol nejkratší možnou dobu platnosti, která je kompatibilní s tvým případem použití. Pokud je token zachycen, změní desetiminutová platnost potenciálně vážný incident v drobnou nepříjemnost.
Implementace backendu
Zde je příklad bezpečné proxy v Node.js:
// Trasa backendu - NIKDY nezveřejňuj na straně klienta
app.post("/api/realtime-token", authenticateUser, 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 }
})
}
);
const token = await response.json();
res.json({ token: token.value, expires_at: token.expires_at });
});
Tři detaily v tomto příkladu nesou celou bezpečnost nastavení. API klíč žije v proměnné prostředí serveru, nikdy v kódu. Middleware authenticateUser ověří identitu uživatele před vydáním tokenu – bez něj by kdokoli mohl získat tokeny a čerpat tvou kvótu na tvé náklady. A klientovi je vrácen pouze efemérní token, nikdy klíč.
Několik úskalí se v recenzích kódu objevuje pravidelně. API klíč proklouzl do frontendu „jen pro prototyp“ a nevyhnutelně skončil v produkci. Token vytvářený systematicky s maximální dobou platnosti pro pohodlí, když případ použití vyžaduje čtvrtinu této doby. Koncový bod pro generování ponechaný bez ověření autentizace, otevřený všem. A chybějící obsluha obnovy na straně klienta, což produkuje chyby vypršení platnosti uprostřed relace místo transparentního opětovného připojení: protože odpověď obsahuje expires_at, má tvůj klient vše potřebné k vyžádání nového tokenu před termínem, nikoli až po něm.
Klíčové poznatky
- Efemérní tokeny umožňují ověření WebSocket bez prozrazení tvého API klíče
- Koncový bod:
POST /v1/realtime/client_secrets(volání pouze na straně serveru) - Nastavitelná doba platnosti od několika sekund až po maximum 3600 sekund (výchozí: 600 s)
- Tvůj backend funguje jako autentizační proxy mezi klientem a xAI
- Vždy zvol nejkratší dobu platnosti kompatibilní s tvým použitím