Hitelesítés és ideiglenes tokenek
Ezen az oldalon
Két hitelesítési módszer
A Voice Agent API két lehetőséget kínál a WebSocket-kapcsolat hitelesítésére. A választás attól függ, hogy a kódod hol fut: szerveroldalon vagy kliensoldalon.
Közvetlen API-kulcs (szerveroldal)
A legegyszerűbb módszer, ha az API-kulcsodat az authorization fejlécben adod meg a WebSocket megnyitásakor. Ez szerveralkalmazásoknál működik, ahol a kulcs védett marad:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Soha ne használd ezt a módszert olyan kódban, amely a böngészőben fut: az API-kulcs láthatóvá válna a forráskódban vagy a fejlesztői eszközökben.
Ideiglenes tokenek (kliensoldal)
Frontend alkalmazásokhoz (böngésző, mobil) az xAI ideiglenes tokeneket biztosít. A backended generál egy rövid élettartamú tokent, amelyet aztán átadsz a kliensnek a WebSocket-kapcsolat megnyitásához.
A tokent egy POST kéréssel hozod létre:
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}}'
Az expires_after.seconds mező határozza meg, hogy a token mennyi ideig érvényes, másodpercben. A hivatalos dokumentáció példája 300 másodpercet (5 percet) használ: az ideiglenes token célja egy hangmunkamenet lefedése, nem pedig a tartós érvényesség. Törekedj a munkameneteidhez igazított legrövidebb élettartamra.
Ajánlott architektúra ideiglenes tokenekkel
Íme a teljes folyamat egy webalkalmazáshoz:
// 1. Szerveroldal (Node.js/Express): a token generálása
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 } })
}
);
// Az xAI válasz törzsének visszaadása változatlanul;
// ez tartalmazza az ideiglenes tokent
res.json(await response.json());
});
// 2. Kliensoldal (böngésző): a token használata
// A böngésző WebSocket konstruktora nem fogad el fejléceket:
// a token egy SUBPROTOCOL-ba kerül, "xai-client-secret." előtaggal.
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");
};
}
Tokenek megújítása
A dokumentáció nem tér ki arra, hogy egy lejáró token bezárja-e a már nyitott kapcsolatot. Mindenesetre az alkalmazásodnak rendelkeznie kell tervvel a kapcsolat megszakadására: figyeld a close eseményt, kérj új tokent a backendedtől, majd csatlakozz újra:
ws.onclose = async () => {
// Kapcsolat megszakadt vagy lezárult: új token kérése
const newToken = await fetchNewToken();
reconnect(newToken);
};
Biztonsági legjobb gyakorlatok
Néhány alapvető szabály biztosítja kapcsolataid biztonságát:
- Soha ne tedd ki a fő API-kulcsodat a kliensoldalon
- Tartsd az élettartamot (
expires_after.seconds) a lehető legrövidebbre: ha az átlagos munkamenet öt percig tart, a 300–600 másodperc elegendő - Érvényesítsd a tokenkéréseket a szerveren (felhasználói hitelesítés, sebességkorlátozás)
- Naplózd a tokenek létrehozását, hogy felismerd a rendellenes használatot
- Cseréld le a fő API-kulcsodat, ha gyanakszol a kompromittálódására
Főbb megállapítások
- A közvetlen API-kulcs kizárólag szerveralkalmazásokhoz alkalmas
- Az ideiglenes tokenek elengedhetetlenek a kliensoldali alkalmazásokhoz (böngésző, mobil)
- Az élettartamot az
expires_after.secondsparaméterrel állítsd be, és tartsd rövideen (a hivatalos példában 300 másodperc) - Az ajánlott folyamat: a backended generálja a tokent, a frontend pedig az
xai-client-secret.alprotokollként adja meg a WebSocket megnyitásához - Mindig tervezz automatikus tokenmegújítást