Efemérne tokeny a bezpečnosť
Na tejto strane
Aktualizované 3. novembra 2026 na základe referencie xAI Voice API. Zdroje: Efemérne tokeny · Referencia Voice API · Obnovenie relácie.
Problém s API kľúčom na strane klienta
Hlasová aplikácia bežiaca v prehliadači alebo na telefóne nemôže obsahovať tvoj API kľúč. Každý návštevník môže otvoriť vývojárske nástroje, prečítať kľúč z JavaScript zväzku alebo hlavičky požiadavky a následne ho využiť na tvojom účte, kým sa nevyčerpá tvoja kvóta. Žiadne množstvo maskovania neochráni hodnotu, ktorú musí klient mať, aby mohol volať API.
Riešením od xAI sú efemérne tokeny, nazývané aj klientové tajomstvá: krátkodobý token, generovaný tvojim serverom, ktorý autorizuje hlasovú reláciu a nič iné.
Ako to funguje
Celý proces sa skladá z piatich krokov:
- Tvoj backend (zabezpečený server) zavolá
POST /v1/realtime/client_secretss tvojím API kľúčom - API vráti dočasný token s obmedzenou životnosťou
- Tvoj backend odošle tento token klientovi (prehliadač alebo mobilná aplikácia)
- Klient použije token na pripojenie k WebSocketu Voice Agent
- Token vyprší po uplynutí zvolenej životnosti (
expires_after.seconds)
To, čo môže uniknúť na strane klienta, má teraz oveľa menšiu hodnotu: token, ktorý vyprší v priebehu niekoľkých minút a dokáže otvoriť iba hlasovú reláciu, nie tvoj API kľúč. Na serveri trvá jeho vygenerovanie len niekoľko riadkov kódu. Všimni si, že handler začína kontrolou používateľa: bez tejto kontroly by sa tvoj backend stal len verejným výdajcom tokenov.
// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
// Skontroluj, či je používateľ autentifikovaný
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 minút, predvolená hodnota
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Klient pozná iba tvoju vlastnú trasu: požiada o token a následne s ním otvorí WebSocket.
// Frontend (prehliadač)
async function startVoiceSession() {
// Požiadaj backend o token
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// Webový socket v prehliadači neprijíma hlavičky:
// token sa odovzdáva v subprotokole s predponou "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... konfigurácia relácie
}
Architektúra end-to-end
Všetko dohromady začína prihlásením používateľa do tvojej aplikácie. Jeho klient potom požiada tvoj backend o hlasový token, pričom backend pred vygenerovaním efemérneho tokena cez xAI API skontroluje autentifikáciu a oprávnenia. Token putuje späť ku klientovi, ktorý ho použije na otvorenie relácie Voice Agent a na konci svojej životnosti automaticky vyprší.
Táto kontrola medzi požiadavkou a generovaním mení jednoduché relé na kontrolný bod, a práve tu žijú tvoje obchodné pravidlá. Môžeš obmedziť počet hlasových relácií na používateľa za deň, aby jeden účet nemohol cez noc minúť tvoj mesačný rozpočet. Tokeny môžeš vyhradiť pre aktívne predplatné a presadzovať svoj obchodný model inde než v rozhraní. Môžeš obmedziť frekvenciu požiadaviek, aby chybný alebo škodlivý klient nemohol žiadať tisíc tokenov za minútu. A môžeš logovať každý vygenerovaný token: je to tvoj jediný spoľahlivý základ pre monitorovanie, interné fakturovanie a analýzu incidentov.
Pravidlá, ktoré nikdy nesmieš porušiť
API kľúč sa nikdy nedostane ku klientovi, v žiadnej forme. Udržuj ho mimo front-end JavaScriptu a mimo akýchkoľvek premenných prostredia vystavených zostave prehliadača (premenné s predponou určenou na vloženie do zväzku sa stanú verejnými). Udržuj ho tiež mimo URL adries, logov a chybových hlásení zobrazovaných používateľom.
Ďalej udržuj životnosť čo najkratšiu, ako je to praktické. Podľa referencie API sa expires_after.seconds predvolene nastavuje na 600 sekúnd a maximum je 3 600; dokumentácia vo svojich príkladoch používa 300. Predovšetkým musí byť token platný v momente, keď klient otvorí spojenie. Krátka životnosť zmenšuje okno, počas ktorého môže byť zachytený token zneužitý.
Dokumentácia neuvádza, či expirujúci token preruší už otvorené spojenie. Ak sa tvoj klient potrebuje znovu pripojiť po výpadku siete alebo počas veľmi dlhej relácie, vyžiadaj si nový token a použi obnovenie relácie: povoľ resumption.enabled v session.update, uchovaj ID, ktoré dostaneš v conversation.created, a potom znovu otvor WebSocket s ?conversation_id=<id>. Predchádzajúce kroky sa prehrajú znova 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 } }, // odoslať znova pri každom pripojení
}));
return ws;
}
Pre TTS v režime HTTP existuje ešte jednoduchšia alternatíva k tokenom: proxy. Klient odošle svoj text tvojmu backendu, tvoj backend zavolá TTS a vráti audio. Kľúč nikdy neopustí tvoj server a ty získavaš prirodzené miesto na filtrovanie obsahu a meranie využitia cestou.
Kľúčové poznatky
- Efemérne tokeny zabezpečujú prístup k Voice Agent z aplikácií na strane klienta
POST /v1/realtime/client_secretsvraciavalueaexpires_at;expires_after.secondsmá predvolenú hodnotu 600 a maximum 3 600- V prehliadači sa token odovzdáva v subprotokole
xai-client-secret.<token> - Tvoj backend musí pred vygenerovaním tokena skontrolovať autentifikáciu a oprávnenia
- Nikdy nevystavuj svoj API kľúč na strane klienta, v URL adresách ani v logoch
- Pre HTTP TTS je proxyovanie cez tvoj backend platnou alternatívou k efemérnym tokenom