Overovanie a prechodné tokeny
Na tejto strane
Dva spôsoby overenia
API Voice Agent ponúka dva spôsoby overenia vášho WebSocket pripojenia. Výber závisí od toho, kde beží váš kód: na serveri alebo na strane klienta.
Priamy API kľúč (serverová strana)
Najjednoduchšou metódou je odovzdanie vášho API kľúča v hlavičke authorization pri otváraní WebSocketu. Toto funguje pre serverové aplikácie, kde zostáva kľúč chránený:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Túto metódu nikdy nepoužívajte v kóde, ktorý beží v prehliadači: API kľúč by sa odhalil v zdrojovom kóde alebo vo vývojárskych nástrojoch.
Prechodné tokeny (klientská strana)
Pre front-endové aplikácie (prehliadač, mobilné zariadenia) poskytuje xAI prechodné tokeny. Váš backend vygeneruje krátkodobý token, ktorý následne odovzdáte klientovi na otvorenie WebSocket pripojenia.
Token vytvoríte pomocou požiadavky POST:
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}}'
Pole expires_after.seconds určuje, ako dlho je token platný, v sekundách. Príklad v oficiálnej dokumentácii používa 300 sekúnd (5 minút): prechodný token má pokryť hlasovú reláciu, nie trvať večne. Snažte sa nastaviť čo najkratšiu životnosť, ktorá vyhovuje vašim reláciám.
Odporúčaná architektúra s prechodnými tokenmi
Tu je kompletný tok pre webovú aplikáciu:
// 1. Serverová strana (Node.js/Express): vygenerovanie tokenu
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 } })
}
);
// Vrátite telo odpovede xAI tak, ako je;
// obsahuje prechodný token
res.json(await response.json());
});
// 2. Klientská strana (prehliadač): použitie tokenu
// Konštruktor WebSocket v prehliadači neprijíma hlavičky:
// token sa odovzdáva v SUBPROTOCOL s predponou "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");
};
}
Obnova tokenov
Dokumentácia nešpecifikuje, či expirujúci token uzavrie už otvorené pripojenie. V každom prípade potrebuje vaša aplikácia plán pre prípad vypadnutia pripojenia: sledujte udalosť uzavretia, požiadajte backend o nový token a potom sa znovu pripojte:
ws.onclose = async () => {
// Pripojenie stratené alebo uzavreté: vyžiadať nový token
const newToken = await fetchNewToken();
reconnect(newToken);
};
Najlepšie postupy zabezpečenia
Niekoľko zásadných pravidiel udrží vaše pripojenia v bezpečí:
- Nikdy neodhaľujte svoj hlavný API kľúč na strane klienta
- Udržujte životnosť (
expires_after.seconds) čo najkratšiu: ak vaša priemerná relácia trvá päť minút, stačí 300 až 600 sekúnd - Overujte požiadavky na tokeny na serveri (overenie používateľa, obmedzenie rýchlosti)
- Logujte vytváranie tokenov, aby ste odhalili abnormálne využitie
- Rotujte svoj hlavný API kľúč, ak máte podozrenie na jeho kompromitáciu
Kľúčové poznatky
- Priamy API kľúč je vhodný len pre serverové aplikácie
- Prechodné tokeny sú nevyhnutnosťou pre klientské aplikácie (prehliadač, mobilné zariadenia)
- Životnosť tokenu nastavte pomocou
expires_after.secondsa udržujte ju krátku (v oficiálnom príklade 300 sekúnd) - Odporúčaný tok: váš backend vygeneruje token a váš front-end ho odovzdá ako subprotokol
xai-client-secret.na otvorenie WebSocketu - Vždy plánujte automatickú obnovu tokenov