Efemérní tokeny a bezpečnost
Na této stránce
Aktualizováno 3. listopadu 2026 na základě reference k xAI Voice API. Zdroje: Efemérní tokeny · Reference k Voice API · Obnovení relace.
Problém s API klíčem na straně klienta
Hlasová aplikace běžící v prohlížeči nebo na telefonu nemůže obsahovat tvůj API klíč. Jakýkoli návštěvník může otevřít vývojářské nástroje, přečíst klíč z JavaScript balíčku nebo hlavičky požadavku a následně jej využít na tvém účtu, dokud se nevyčerpá tvoje kvóta. Žádné množství zastírání kódu (obfuscation) neochrání hodnotu, kterou musí klient mít k dispozici, aby mohl volat API.
Řešením od xAI jsou efemérní tokeny, nazývané také klientská tajemství (client secrets): krátkodobý token generovaný tvým serverem, který autorizuje pouze hlasovou relaci a nic jiného.
Jak to funguje
Celý proces se skládá z pěti kroků:
- Tvůj backend (zabezpečený server) zavolá
POST /v1/realtime/client_secretss tvým API klíčem. - API vrátí dočasný token s omezenou životností.
- Tvůj backend odešle tento token klientovi (prohlížeči nebo mobilní aplikaci).
- Klient použije token k připojení k WebSocketu Voice Agent.
- Token po uplynutí zvolené doby životnosti (
expires_after.seconds) vyprší.
To, co může na straně klienta uniknout, má nyní mnohem menší hodnotu: token, který vyprší během několika minut a slouží pouze k otevření hlasové relace, nikoli tvůj API klíč. Na serveru trvá jeho generování jen několik řádků kódu. Všimni si, že handler začíná kontrolou uživatele: bez této kontroly by se tvůj backend stal pouze veřejným výdejníkem tokenů.
// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
// Zkontroluj, zda je uživatel autentizován
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 minut, výchozí hodnota
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Klient zná pouze tvou vlastní trasu: požádá o token a poté s ním otevře WebSocket.
// Frontend (prohlížeč)
async function startVoiceSession() {
// Požádej backend o token
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// Webový socket v prohlížeči nepřijímá hlavičky:
// token se předává v subprotokolu s prefixem "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... konfigurace relace
}
Architektura end-to-end
Když vše spojíš dohromady, proces začíná přihlášením uživatele do tvé aplikace. Jeho klient si poté vyžádá od tvého backendu hlasový token. Backend před vygenerováním efemérního tokenů prostřednictvím xAI API zkontroluje autentizaci a oprávnění. Token putuje zpět ke klientovi, který jej použije k otevření relace Voice Agent, a na konci své životnosti automaticky vyprší.
Tato kontrola mezi žádostí a generováním mění jednoduché předávání dat v kontrolní bod, a právě zde žijí tvá obchodní pravidla. Můžeš omezit počet hlasových relací na uživatele za den, aby jeden účet nespálil tvůj měsíční rozpočet přes noc. Můžeš vyhradit tokeny pro aktivní předplatné a vynucovat svůj obchodní model jinde než v rozhraní. Můžeš omezit frekvenci požadavků (rate-limiting), aby chybný nebo škodlivý klient nemohl žádat o tisíce tokenů za minutu. A můžeš logovat každý vygenerovaný token: je to tvůj jediný spolehlivý základ pro monitorování, interní fakturaci a analýzu incidentů.
Pravidla, která nikdy nesmíš porušit
API klíč se nikdy nedostane ke klientovi, v žádné podobě. Udržuj jej mimo front-end JavaScript a mimo jakoukoli proměnnou prostředí vystavenou sestavení pro prohlížeč (proměnné určené k vložení do balíčku skončí veřejné). Udržuj jej také mimo URL, logy a chybové zprávy zobrazované uživatelům.
Dále udržuj životnost co nejkratší, jak je praktické. Podle reference k API se expires_after.seconds ve výchozím nastavení rovná 600 sekundám a maximálně dosahuje 3 600; dokumentace ve svých příkladech používá 300. Především musí být token platný v okamžiku, kdy klient otevírá připojení. Krátká životnost zmenšuje časové okno, během kterého lze zachycený token zneužít.
Dokumentace neuvádí, zda expirující token přeruší již otevřené připojení. Pokud se tvůj klient potřebuje znovu připojit po výpadku sítě nebo během velmi dlouhé relace, vyžádej si nový token a použij obnovení relace (session resumption): povol resumption.enabled v session.update, uchovej ID přijaté v conversation.created a poté znovu otevři WebSocket s ?conversation_id=<id>. Předchozí kroky se přehrají a model pokračuje tam, kde skončil.
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 } }, // odeslat znovu při každém připojení
}));
return ws;
}
Pro TTS v režimu HTTP existuje ještě jednodušší alternativa k tokenům: proxy. Klient odešle svůj text tvému backendu, tvůj backend zavolá TTS a vrátí zvuk. Klíč nikdy neopustí tvůj server a ty získáš přirozené místo pro filtrování obsahu a měření využití cestou.
Klíčové poznatky
- Efemérní tokeny zabezpečují přístup k Voice Agent z aplikací na straně klienta
POST /v1/realtime/client_secretsvracívalueaexpires_at;expires_after.secondsmá výchozí hodnotu 600 a maximum 3 600- V prohlížeči se token předává v subprotokolu
xai-client-secret.<token> - Tvůj backend musí před vygenerováním tokenů zkontrolovat autentizaci a oprávnění
- Nikdy nevystavuj svůj API klíč na klientovi, v URL ani v logách
- Pro HTTP TTS je validní alternativou k efemérním tokenům proxyování přes tvůj backend