Īslaicīgi žetoni WebSocket savienojumiem
Šajā lapā
Problēma: klienta autentificēšana, neatklājot savu atslēgu
Veidojot balss vai reāllaika lietotni ar Grok API, tev ir jāizveido WebSocket savienojums tieši no pārlūka vai mobilās ierīces klienta. Datu plūsmas maršrutēšana caur savu serveri rada aizkavi, kas izjauc plūstošu balss sarunu. Taču tiešie savienojumi rada autentifikācijas problēmu: tev nekādā gadījumā nedrīkst iekļaut savu API atslēgu klienta puses kodā.
Iemesls ir vienkāršs: jebkura atslēga, kas iegulta frontend JavaScript kodā, dekompilējamā mobilajā lietotnē vai izplatītā binārajā failā, tiek apdraudēta brīdī, kad to publicē. Jebkurš lietotājs var atvērt savu pārlūka izstrādātāja rīkus un to nolasīt. Lai to atrisinātu, xAI piedāvā īslaicīgus žetonus: pagaidu žetonus, kurus klienti var izmantot, nekad neredzot galveno atslēgu.
Kā darbojas īslaicīgi žetoni
Arhitektūra balstās uz vienu principu: API atslēga nekad neatstāj tavu serveri, un klients saņem tikai īsu dzīves laiku esošu žetonu. Plūsma ir īsa. Klients pieprasa žetonu no sava backend, kas veic izsaukumu POST /v1/realtime/client_secrets, izmantojot tavu API atslēgu. Šis izsaukums ir vienīgā vieta, kur parādās atslēga, un tas notiek pilnībā servera pusē. xAI atgriež īslaicīgu žetonu ar tā derīguma termiņu, ko tavs backend nodod klientam. Pēc tam klients atver WebSocket savienojumu ar wss://api.x.ai/v1/realtime, prezentējot šo žetonu. Nevienā brīdī pārlūks neredz galveno atslēgu; tas apstrādā žetonu, kurš beidzas pats par sevi.
Žetona izveides izsaukums no tava backend izskatās šādi:
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}}'
Un atbilde:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Attiecībā uz ilgumu tev ir trīs atsauces punkti: nav dokumentēta minimālā robeža (ir iespējamas dažas sekundes), noklusējuma vērtība ir 600 sekundes (10 minūtes), un maksimums ir 3600 sekundes (1 stunda).
Pareizā ilguma izvēle
Žetona ilgumam ir jāatbilst tavam lietojuma gadījumam, un šī izvēle ir patiesi drošības lēmums. Retām balss mijiedarbībām – jautājumu un atbilžu sesijai, balss komandai, diktēšanai – pietiek ar 300 līdz 600 sekunžu logu: sesija beigsies ilgi pirms termiņa beigām. Ilgstošām balss sarunām, piemēram, klientu atbalstam, intervijai vai asistētai sapulcei, mērķē uz 600 līdz 1800 sekundēm, lai izvairītos no savienojuma pārtraukšanas sarunas vidū. Ilgstošām darba sesijām – reāllaika transkribēšanai, nepārtrauktai balss uzraudzībai – var attaisnot 1800 līdz 3600 sekundes, taču izmanto maksimālo ilgumu piesardzīgi: tas paplašina izmantošanas logu, ja žetons tiek nozagts.
Zelta likums ir šāds: vienmēr izvēlies īsāko ilgumu, kas ir savienojams ar tavu lietojuma gadījumu. Ja žetons tiek pārtverts, desmit minūšu derīguma termiņš pārvērš potenciāli nopietnu incidentu nelielās neērtībās.
Backend implementācija
Lūk, droša starpniekservera (proxy) piemērs Node.js vidē:
// Backend maršruts - NEKĀDĀ GADĪJUMĀ neizpaud klienta pusē
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 });
});
Šajā piemērā trīs detaļas nodrošina visas iestatījuma drošību. API atslēga atrodas servera vides mainīgajā, nekad kodā. authenticateUser starpprogrammatūra pārbauda lietotāja identitāti pirms žetona izsniegšanas – bez tās jebkurš varētu iegūt žetonus un iztērēt tavu kvotu uz tava rēķina. Un klientam tiek atgriezts tikai īslaicīgais žetons, nekad ne atslēga.
Koda apskatos regulāri rodas daži tipiski trūkumi. API atslēga, kas “tikai prototipam” ieviesta frontend, neizbēgami nonāk produkcijā. Žetons, kas ērtības labad sistemātiski tiek izveidots ar maksimālo ilgumu, lai gan lietojuma gadījumam pietiek ar ceturtdaļu no tā. Ģenerēšanas galapunkts, kas atstāts bez autentifikācijas pārbaudes, ir pieejams visiem. Un atjaunošanas apstrādes trūkums klienta pusē, kas rada derīguma termiņa kļūdas sesijas vidū, nevis caurspīdīgu atkārtotu savienojumu: tā kā atbilde sniedz expires_at, tavam klientam ir viss nepieciešamais, lai pieprasītu jaunu žetonu pirms termiņa beigām, nevis pēc tām.
Galvenās atziņas
- Īslaicīgi žetoni ļauj veikt WebSocket autentifikāciju, neatklājot savu API atslēgu
- Galapunkts:
POST /v1/realtime/client_secrets(tikai servera puses izsaukums) - Konfigurējams ilgums no dažām sekundēm līdz maksimāli 3600 sekundēm (noklusējums: 600s)
- Tavs backend darbojas kā autentifikācijas starpnieks starp klientu un xAI
- Vienmēr izvēlies īsāko ilgumu, kas atbilst tavam lietojumam