Efemérne tokeny pre WebSocket pripojenia
Na tejto strane
Problém: autentifikácia klienta bez odhalenia vášho kľúča
Pri tvorbe hlasových aplikácií alebo aplikácií v reálnom čase s využitím Grok API potrebuješ nadviazať WebSocket pripojenie priamo z prehliadača alebo mobilného klienta. Smerovanie prevádzky cez tvoj server pridáva oneskorenie, ktoré narúša plynulosť hlasovej konverzácie. Priame pripojenia však vytvárajú problém s autentifikáciou: nikdy nesmieš zahrnúť svoj API kľúč do kódu na strane klienta.
Dôvod je jednoduchý: akýkoľvek kľúč vložený do frontendového JavaScriptu, dekompilovateľnej mobilnej aplikácie alebo distribuovaného binárneho súboru je kompromitovaný v momente jeho publikovania. Každý používateľ môže otvoriť vývojárske nástroje prehliadača a prečítať si ho. Na vyriešenie tohto problému xAI ponúka efemérne tokeny: dočasné tokeny, ktoré môžu klienti používať bez toho, aby kedykoľvek videli hlavný kľúč.
Ako fungujú efemérne tokeny
Architektúra sa riadi jedným princípom: API kľúč nikdy neopustí tvoj server a klient dostane iba krátkodobý token. Tok je stručný. Klient požiada tvoj backend o token, ktorý následne zavolá POST /v1/realtime/client_secrets s tvojím API kľúčom. Toto volanie je jediným miestom, kde sa kľúč objaví, a deje sa výlučne na strane servera. xAI vráti efemérny token s dátumom jeho vypršania platnosti, ktorý tvoj backend odovzdá klientovi. Klient následne otvorí WebSocket pripojenie na wss://api.x.ai/v1/realtime a predloží tento token. Hlavný kľúč sa v žiadnom momente nedostane do prehliadača; ten pracuje s tokenom, ktorý sám od seba expiruje.
Volanie na vytvorenie z tvojho backendu vyzerá 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 odpoveď:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Pokiaľ ide o dĺžku platnosti, máš k dispozícii tri referenčné hodnoty: nie je zdokumentované žiadne minimum (možných je niekoľko sekúnd), predvolená hodnota je 600 sekúnd (10 minút) a maximum je 3600 sekúnd (1 hodina).
Výber správnej dĺžky platnosti
Dĺžka platnosti tokenu musí zodpovedať tvojmu prípadu použitia a táto voľba predstavuje skutočné bezpečnostné rozhodnutie. Pre sporadické hlasové interakcie – otázky a odpovede, hlasové príkazy, diktovanie – postačuje okno 300 až 600 sekúnd: relácia sa skončí dávno pred vypršaním platnosti. Pre dlhšie hlasové konverzácie, ako je zákaznícka podpora, pohovor alebo asistované stretnutie, cieľ na 600 až 1800 sekúnd, aby sa predišlo prerušeniu uprostred rozhovoru. Dlhé pracovné relácie – prepis v reálnom čase, nepretržité monitorovanie hlasu – môžu odôvodniť 1800 až 3600 sekúnd, ale maximálnu dĺžku platnosti používaj opatrne: rozširuje časové okno pre zneužitie v prípade odcudzenia tokenu.
Zlaté pravidlo znie takto: vždy vyber najkratšiu možnú dĺžku platnosti, ktorá je kompatibilná s tvojím prípadom použitia. Ak je token zachytený, desaťminútová expirácia zmení potenciálne vážny incident na menšiu nepríjemnosť.
Implementácia na backende
Tu je príklad bezpečného proxy servera v Node.js:
// Trasa backendu - NIKDY neodhaľuj na strane 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 });
});
Tri detaily v tomto príklade nesú celú bezpečnosť nastavenia. API kľúč sa nachádza v premennej prostredia servera, nikdy nie v kóde. Middleware authenticateUser overí identitu používateľa pred vydaním tokenu – bez neho by ktokoľvek mohol získať tokeny a míňať tvoju kvótu na tvoje náklady. A klientovi sa vráti iba efemérny token, nikdy nie kľúč.
Pri kontrolách kódu sa pravidelne objavuje niekoľko úskalí. API kľúč prenikne do frontendu „len pre prototyp“ a nevyhnutne sa dostane do produkcie. Token sa vytvára systematicky s maximálnou dĺžkou platnosti kvôli pohodliu, hoci prípad použitia vyžaduje štvrtinu tohto času. Koncový bod generovania zostane bez overenia autentifikácie, otvorený pre všetkých. A chýba obsluha obnovy na strane klienta, čo vedie k chybám vypršania platnosti uprostred relácie namiesto transparentného opätovného pripojenia: keďže odpoveď obsahuje expires_at, tvoj klient má všetko potrebné na vyžiadanie nového tokenu pred uplynutím lehoty, nie až po nej.
Kľúčové poznatky
- Efemérne tokeny umožňujú autentifikáciu WebSocket bez odhalenia tvojho API kľúča
- Koncový bod:
POST /v1/realtime/client_secrets(volanie výlučne na strane servera) - Konfigurovateľná dĺžka platnosti od niekoľkých sekúnd až po maximálne 3600 sekúnd (predvolené: 600 s)
- Tvoj backend funguje ako autentifikačné proxy medzi klientom a xAI
- Vždy vyber najkratšiu dĺžku platnosti kompatibilnú s tvojím použitím