Autentifikavimas ir laikinieji žetonai
Šiame puslapyje
Du autentifikavimo būdai
Voice Agent API siūlo du būdus autentifikuoti savo WebSocket ryšį. Kurį pasirinkti, priklauso nuo to, kur veikia tavo kodas: serveryje ar kliento pusėje.
Tiesioginis API raktas (serverio pusė)
Paprastiausias būdas – perduoti savo API raktą „Authorization“ antraštėje atidarant WebSocket. Tai tinka serverio programoms, kur raktas lieka apsaugotas:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Niekada nenaudok šio metodo kode, kuris vykdoma naršyklėje: API raktas būtų atskleistas源代码 arba kūrėjo įrankiuose.
Laikinieji žetonai (kliento pusė)
Front-end programoms (naršyklė, mobiliosios) xAI suteikia laikinuosius žetonus. Tavo backendas sugeneruoja trumpalaikį žetoną, kurį tada perduodi klientui WebSocket ryšiui užmegzti.
Žetoną sukuri siųsdami POST užklausą:
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": 300}}'
Laukas expires_after.seconds nustato, kiek sekundžių žetonas galioja. Oficialioje dokumentacijoje pateiktame pavyzdyje naudojama 300 sekundžių (5 minutės): laikinasis žetonas skirtas padengti balso sesiją, o ne egzistuoti ilgai. Siek kuo trumpesnio galiojimo laiko, kuris tinka tavo sesijoms.
Rekomenduojama architektūra su laikinaisiais žetonais
Štai visas srautas žiniatinklio programai:
// 1. Serverio pusė (Node.js/Express): sugeneruoti žetoną
app.post("/api/realtime-token", 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 } })
}
);
// Grąžinti xAI atsakymo kūną tokį, koks yra;
// jame yra laikinasis žetonas
res.json(await response.json());
});
// 2. Kliento pusė (naršyklė): naudoti žetoną
// Naršyklės WebSocket konstruktorius nepriima antraščių:
// žetonas perduodamas kaip SUBPROTOCOL, priešdėlis „xai-client-secret.“
async function startVoiceSession(ephemeralToken) {
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime",
[`xai-client-secret.${ephemeralToken}`]
);
ws.onopen = () => {
console.log("Voice session started");
};
}
Žetonų atnaujinimas
Dokumentacijoje nenurodyta, ar baigiantis žetono galiojimui uždaromas jau atidarytas ryšys. Bet kuriuo atveju tavo programa turi turėti planą ryšiui nutrūkus: stebėk uždarymo įvykį, paprašyk backendo naujo žetono ir prisijunk iš naujo:
ws.onclose = async () => {
// Ryšys nutrūko arba uždarytas: prašyti naujo žetono
const newToken = await fetchNewToken();
reconnect(newToken);
};
Saugumo geriausios praktikos
Keletas esminių taisyklių užtikrins tavo ryšių saugumą:
- Niekada neatskleisk savo pagrindinio API rakto kliento pusėje
- Laikyk galiojimo laiką (
expires_after.seconds) kuo trumpesnį: jei vidutinė sesija trunka penkias minutes, pakanka 300–600 sekundžių - Tikrink žetonų užklausas serveryje (vartotojo autentifikavimas, užklausų ribojimas)
- Registruok žetonų kūrimą, kad galėtum pastebėti neįprastą naudojimą
- Pakeisk savo pagrindinį API raktą, jei įtari, kad jis buvo pažeistas
Svarbiausi punktai
- Tiesioginis API raktas tinka tik serverio programoms
- Laikinieji žetonai yra būtini kliento pusės programoms (naršyklė, mobiliosios)
- Nustatyk žetono galiojimo laiką naudodamas
expires_after.secondsir laikyk jį trumpą (oficialiame pavyzdyje – 300 sekundžių) - Rekomenduojamas srautas: tavo backendas sugeneruoja žetoną, o front-endas jį perduoda kaip
xai-client-secret.subprotokolą WebSocket ryšiui užmegzti - Visada numatyk automatinį žetonų atnaujinimą