Ephemerni tokeni za WebSocket veze
Na ovoj stranici
Problem: autentifikacija klijenta bez otkrivanja ključa
Kada gradiš glasovnu aplikaciju ili aplikaciju u stvarnom vremenu s Grok API-jem, moraš uspostaviti WebSocket vezu izravno iz preglednika ili mobilnog klijenta. Preusmjeravanje prometa kroz tvoj poslužitelj dodaje kašnjenje koje prekida fluidan glasovni razgovor. No izravne veze stvaraju problem autentifikacije: nikada ne smiješ uključiti svoj API ključ u kôd na strani klijenta.
Razlog je jednostavan: svaki ključ ugrađen u JavaScript na frontendu, mobilnu aplikaciju koju je moguće dekompajlirati ili distribuirani binarni kod kompromitiran je čim ga objaviš. Svaki korisnik može otvoriti razvojne alate preglednika i pročitati ga. Da bi se to riješilo, xAI nudi ephemerne tokene: privremene tokene koje klijenti mogu koristiti, a da pritom nikada ne vide glavni ključ.
Kako funkcioniraju ephemerni tokeni
Arhitektura slijedi jedno načelo: API ključ nikada ne napušta tvoj poslužitelj, a klijent prima samo token kratkog vijeka trajanja. Tijek je kratak. Klijent traži token od tvog backenda, koji poziva POST /v1/realtime/client_secrets s tvojim API ključem. Taj je poziv jedino mjesto gdje se ključ pojavljuje i odvija se u potpunosti na strani poslužitelja. xAI vraća ephemerni token s datumom isteka, koji tvoj backend prosljeđuje klijentu. Klijent zatim otvara WebSocket vezu na wss://api.x.ai/v1/realtime prezentirajući taj token. U nijednom trenutku preglednik ne vidi glavni ključ; rukuje tokenom koji sam istječe.
Poziv za stvaranje s tvog backenda izgleda ovako:
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 odgovor:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Što se tiče trajanja, imaš tri referentne točke: ne postoji dokumentirani minimum (moguće je nekoliko sekundi), zadana vrijednost je 600 sekundi (10 minuta), a maksimum je 3600 sekundi (1 sat).
Odabir ispravnog trajanja
Trajanje tokena mora odgovarati tvom slučaju upotrebe, a taj je izbor prava sigurnosna odluka. Za povremene glasovne interakcije – pitanja i odgovori, glasovne naredbe, diktaf – prozor od 300 do 600 sekundi više je nego dovoljan: sesija će završiti davno prije isteka. Za dugotrajne glasovne razgovore poput korisničke podrške, intervjua ili asistiranog sastanka, ciljaj na 600 do 1800 sekundi kako bi izbjegao prekid usred razgovora. Dugotrajne radne sesije – transkripcija u stvarnom vremenu, kontinuirano glasovno praćenje – mogu opravdati 1800 do 3600 sekundi, no maksimalno trajanje koristi oprezno: ono širi prozor za iskorištavanje ako se token ukrade.
Zlatno pravilo glasi ovako: uvijek odaberi najkraće trajanje kompatibilno s tvojim slučajem upotrebe. Ako se token presretne, istek od deset minuta pretvara potencijalno ozbiljan incident u manju smetnju.
Implementacija backenda
Evo primjera sigurnog proxyja u Node.jsu:
// Ruta backenda - NIKADA ne izlaži na strani klijenta
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 detalja u ovom primjeru nose cjelokupnu sigurnost postavke. API ključ živi u varijabli okruženja poslužitelja, nikada u kodu. Srednji sloj authenticateUser provjerava identitet korisnika prije izdavanja tokena – bez njega bi bilo tko mogao dobiti tokene i trošiti tvoju kvotu o tvom trošku. I samo ephemerni token, nikada ključ, vraća se klijentu.
Nekoliko zamki redovito se pojavljuje u pregledima koda. API ključ koji procuri u frontend „samo za prototip“ neizbježno završi u produkciji. Token se sustavno stvara s maksimalnim trajanjem, radi pogodnosti, iako slučaj upotrebe zahtijeva četvrtinu toga. Krajnja točka generiranja ostaje bez provjere autentifikacije, otvorena svima. I nedostatak rukovanja obnavljanjem na strani klijenta, što proizvodi pogreške isteka usred sesije umjesto transparentnog ponovnog spajanja: budući da odgovor daje expires_at, tvoj klijent ima sve što mu treba da zatraži novi token prije roka, a ne nakon njega.
Ključne točke
- Ephemerni tokeni omogućuju autentifikaciju WebSocketa bez otkrivanja tvog API ključa
- Krajnja točka:
POST /v1/realtime/client_secrets(poziv isključivo na strani poslužitelja) - Podesivo trajanje od nekoliko sekundi do maksimalno 3600 sekundi (zadano: 600s)
- Tvoj backend djeluje kao autentifikacijski proxy između klijenta i xAI-ja
- Uvijek odaberi najkraće trajanje kompatibilno s tvojom upotrebom