Ephemerni žetoni za povezave WebSocket
Na tej strani
Težava: avtentikacija odjemalca brez razkrivanja ključa
Ko gradiš glasovno ali aplikacijo v realnem času z API-jem Grok, moraš vzpostaviti povezavo WebSocket neposredno iz brskalnika ali mobilnega odjemalca. Preusmerjanje prometa skozi tvoj strežnik dodaja zakasnitev, ki poruši tekoč glasovni pogovor. Toda neposredne povezave ustvarjajo težavo z avtentikacijo: svojega ključa API nikoli ne smeš vključiti v kodo na strani odjemalca.
Razlog je preprost: vsak ključ, vgrajen v JavaScript na sprednji strani, mobilno aplikacijo, ki jo je mogoče dekompilirati, ali razdeljeni binarni program, je ogrožen takoj, ko ga objaviš. Vsak uporabnik lahko odpre orodja za razvijalce v brskalniku in ga prebere. Da bi to rešili, xAI ponuja ephemerne žetone: začasne žetone, ki jih odjemalci lahko uporabljajo, ne da bi kdaj videli glavni ključ.
Kako delujejo ephemerni žetoni
Arhitektura sledi enemu načelu: ključ API nikoli ne zapusti tvojega strežnika, odjemalec pa prejme le kratkotrajni žeton. Potek je kratek. Odjemalec zahteva žeton od tvojega zaledja, ki pokliče POST /v1/realtime/client_secrets s tvojim ključem API. Ta klic je edino mesto, kjer se ključ pojavi, in poteka izključno na strani strežnika. xAI vrne ephemerni žeton z datumom poteka, ki ga tvoje zaledje posreduje odjemalcu. Odjemalec nato odpre povezavo WebSocket na wss://api.x.ai/v1/realtime in predloži ta žeton. Brskalnik glavni ključ nikoli ne vidi; upravlja z žetonom, ki samodejno poteče.
Klic za ustvarjanje iz tvojega zaledja izgleda takole:
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}}'
In odgovor:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Glede trajanja imaš tri referenčne vrednosti: dokumentirana spodnja meja ne obstaja (mogočih je nekaj sekund), privzeta vrednost je 600 sekund (10 minut), najvišja pa 3600 sekund (1 ura).
Izbira ustreznega trajanja
Trajanje žetona se mora ujemati s tvojim primerom uporabe, ta izbira pa je prava varnostna odločitev. Za občasne glasovne interakcije – vprašanja in odgovore, glasovne ukaze, diktat – je okno 300 do 600 sekund povsem dovolj: seja se bo končala dolgo pred potekom. Za dolgotrajne glasovne pogovore, kot so podpura strankam, intervjuji ali sestanki s pomočjo, ciljaš na 600 do 1800 sekund, da se izogneš prekinjanju sredi pogovora. Dolgotrajne delovne seje – prepisovanje v realnem času, neprekinjeno glasovno spremljanje – lahko upravičijo 1800 do 3600 sekund, vendar najdaljše trajanje uporabi previdno: razširi okno za izkoriščanje, če je žeton ukraden.
Zlato pravilo se glasi takole: vedno izberi najkrajše trajanje, ki je združljivo s tvojim primerom uporabe. Če je žeton prestrežen, desetminutni potek spremeni potencialno resen incident v manjšo nadlogo.
Implementacija zaledja
Tukaj je primer varnega posrednika v Node.js:
// Pot zaledja - NE izpostavljaj na strani odjemalca
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 podrobnosti v tem primeru nosijo vso varnost nastavitve. Ključ API živi v spremenljivki okolja strežnika, nikoli v kodi. Vmesna programska oprema authenticateUser preveri identiteto uporabnika pred izdajo žetona – brez nje bi lahko kdorkoli pridobil žetone in na tvoje stroške porabil tvojo kvoto. Odjemalcu se vrne le ephemerni žeton, nikoli ključ.
V pregledih kode se redno pojavljajo nekatere past. Ključ API, ki se je v sprednji del „samo za prototip” ponesreči znašel v produkciji. Žeton, sistematično ustvarjen z najdaljšim trajanjem zaradi priročnosti, čeprav primer uporabe zahteva četrtino tega. Končna točka za generiranje, puščena brez preverjanja avtentikacije, odprta za vse. In pomanjkanje obravnave podaljševanja na strani odjemalca, kar povzroča napake poteka sredi seje namesto pregledne ponovne povezave: ker odgovor vsebuje expires_at, ima tvoj odjemalec vse potrebno, da zahteva nov žeton pred rokom in ne po njem.
Ključne ugotovitve
- Ephemerni žetoni omogočajo avtentikacijo WebSocket brez razkrivanja tvojega ključa API
- Končna točka:
POST /v1/realtime/client_secrets(klic samo na strani strežnika) - Konfigurabilno trajanje od nekaj sekund do največ 3600 sekund (privzeto: 600 s)
- Tvoje zaledje deluje kot avtentikacijski posrednik med odjemalcem in xAI
- Vedno izberi najkrajše trajanje, združljivo s tvojo uporabo