Autentifikācija un īslaicīgie pilnvarojumi
Šajā lapā
Divi autentifikācijas veidi
Voice Agent API piedāvā divus veidus, kā autentificēt savu WebSocket savienojumu. Tas, kuru izvēlēsies, ir atkarīgs no tā, kur darbojas tavs kods: serverī vai klientā.
Tiešā API atslēga (servera puse)
Vienkāršākā metode ir norādīt savu API atslēgu autorizācijas galvenē (header), atverot WebSocket. Tas darbojas servera lietotnēm, kur atslēga paliek pasargāta:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Nekad neizmanto šo metodi kodā, kas darbojas pārlūkprogrammā: API atslēga tiktu atklāta pirmkodā vai izstrādātāja rīkos.
Īslaicīgie pilnvarojumi (klienta puse)
Priekšpuses lietotnēm (pārlūkprogramma, mobilās ierīces) xAI nodrošina īslaicīgos pilnvarojumus (ephemeral tokens). Tavs backend ģenerē īsu derīguma termiņu esošu pilnvarojumu, ko pēc tam nodod klientam, lai tas atvērtu WebSocket savienojumu.
Pilnvarojumu izveido, veicot POST pieprasījumu:
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}}'
Lauks expires_after.seconds nosaka, cik ilgi pilnvarojums ir derīgs (sekundēs). Oficiālajā dokumentācijas piemērā izmantoti 300 sekundes (5 minūtes): īslaicīgs pilnvarojums ir paredzēts, lai segtu balss sesiju, nevis lai pastāvētu ilgstoši. Tiecies pēc īsākā iespējamā derīguma termiņa, kas atbilst tavām sesijām.
Ieteicamā arhitektūra ar īslaicīgajiem pilnvarojumiem
Lūk, pilns darbplūsmas apraksts tīmekļa lietotnei:
// 1. Servera puse (Node.js/Express): ģenerē pilnvarojumu
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 } })
}
);
// Atgriež xAI atbildes ķermeni nemainītu;
// tas satur īslaicīgo pilnvarojumu
res.json(await response.json());
});
// 2. Klienta puse (pārlūkprogramma): izmanto pilnvarojumu
// Pārlūkprogrammas WebSocket konstruktors nepieņem galvenes:
// pilnvarojums tiek ievietots apakšprotokolā (SUBPROTOCOL) ar prefiksu "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");
};
}
Pilnvarojumu atjaunošana
Dokumentācijā nav precizēts, vai beidzoties derīguma termiņam, tiek slēgts jau atvērts savienojums. Lai vai kā, tavai lietotnei ir jābūt plānam gadījumam, ja savienojums pārtrūkst: uzraugi aizvēršanas notikumu (close event), pieprasi jaunu pilnvarojumu savam backendam un tad veic atkārtotu savienojumu:
ws.onclose = async () => {
// Savienojums zaudēts vai aizvērts: pieprasa jaunu pilnvarojumu
const newToken = await fetchNewToken();
reconnect(newToken);
};
Drošības labākā prakse
Daži būtiski noteikumi nodrošinās tavu savienojumu drošību:
- Nekad neatklāj savu galveno API atslēgu klientam
- Uzturi derīguma termiņu (
expires_after.seconds) pēc iespējas īsāku: ja tava vidējā sesija ilgst piecas minūtes, pietiek ar 300 līdz 600 sekundēm - Validē pilnvarojumu pieprasījumus serverī (lietotāja autentifikācija, ātruma ierobežošana)
- Reģistrē pilnvarojumu izveidi, lai spētu noteikt neparastu lietojumu
- Rotē savu galveno API atslēgu, ja ir aizdomas par tās kompromitāciju
Galvenās atziņas
- Tieša API atslēga ir piemērota tikai servera lietotnēm
- Īslaicīgie pilnvarojumi ir obligāti klientu puses lietotnēm (pārlūkprogramma, mobilās ierīces)
- Iestati pilnvarojuma derīguma termiņu ar
expires_after.secondsun uzturi to īsu (oficiālajā piemērā – 300 sekundes) - Ieteicamā darbplūsma: tavs backend ģenerē pilnvarojumu, bet tava priekšpuse to nodod kā
xai-client-secret.apakšprotokolu, lai atvērtu WebSocket - Vienmēr plāno automātisku pilnvarojumu atjaunošanu