Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Hitelesítés és ideiglenes tokenek

2. lecke 16 közül Frissítve 2026. július 30. Fejlesztő
Ezen az oldalon
  1. Két hitelesítési módszer
  2. Ajánlott architektúra ideiglenes tokenekkel
  3. Biztonsági legjobb gyakorlatok
  4. Főbb megállapítások

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.seconds paramé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