Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Avtentikacija in efemerna žetona

Lekcija 2 od 16 Posodobljeno 30. julij 2026 Razvijalec
Na tej strani
  1. Dva načina avtentikacije
  2. Priporočena arhitektura z efemernimi žetoni
  3. Najboljše varnostne prakse
  4. Ključne ugotovitve

Dva načina avtentikacije

API za glasovnega agenta ponuja dva načina avtentikacije vaše povezave WebSocket. Izbira je odvisna od tega, kje se izvaja vaša koda: na strežniku ali na odjemalcu.

Neposredni ključ API (strežniška stran)

Najpreprostejša metoda je posredovanje vašega ključa API v glavi za avtorizacijo ob vzpostavitvi povezave WebSocket. To deluje za strežniške aplikacije, kjer ključ ostane zaščiten:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Tega načina nikoli ne uporabljajte v kodi, ki se izvaja v brskalniku: ključ API bi bil razkrit v izvorni kodi ali orodjih za razvijalce.

Efemerna žetona (odjemalska stran)

Za aplikacije na sprednji strani (brskalnik, mobilne naprave) xAI zagotavlja efemerna žetona. Vaše zaledje ustvari kratkotrajno žeton, ki ga nato posredujete odjemalcu za vzpostavitev povezave WebSocket.

Žeton ustvarite z zahtevo 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}}'

Polje expires_after.seconds določa, kako dolgo je žeton veljaven, v sekundah. Primer v uradni dokumentaciji uporablja 300 sekund (5 minut): efemerni žeton je namenjen pokrivanju glasovne seje, ne trajnemu obstoju. Ciljajte na najkrajši možni življenjski čas, ki ustreza vašim sejam.

Priporočena arhitektura z efemernimi žetoni

Tukaj je celoten potek za spletno aplikacijo:

// 1. Strežniška stran (Node.js/Express): generiranje žetona
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 } })
    }
  );
  // Vrnite telo odgovora xAI takšno, kot je;
  // vsebuje efemerni žeton
  res.json(await response.json());
});

// 2. Odjemalska stran (brskalnik): uporaba žetona
// Konstruktor WebSocket v brskalniku ne sprejema glav:
// žeton gre v PODPROTOKOL, s predpono "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");
  };
}

Obnavljanje žetonov

Dokumentacija ne navaja, ali potek žetona zapre že vzpostavljeno povezavo. V vsakem primeru mora vaša aplikacija imeti načrt za primer izgube povezave: spremljajte dogodek zaprtja, od zaledja zahtevajte nov žeton in se ponovno povežite:

ws.onclose = async () => {
  // Povezava izgubljena ali zaprta: zahtevajte nov žeton
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Najboljše varnostne prakse

Nekaj bistvenih pravil zagotavlja varnost vaših povezav:

  • Svojega glavnega ključa API nikoli ne razkrivajte na odjemalcu
  • Ohranite življenjski čas (expires_after.seconds) čim krajši: če vaša povprečna seja traja pet minut, je 300 do 600 sekund dovolj
  • Preverjajte zahteve za žetone na strežniku (avtentikacija uporabnika, omejevanje hitrosti)
  • Beležite ustvarjanje žetonov, da lahko zaznate nenormalno uporabo
  • Zamenjajte svoj glavni ključ API, če sumite, da je bil ogrožen

Ključne ugotovitve

  • Neposredni ključ API je primeren le za strežniške aplikacije
  • Efemerna žetona so nujna za aplikacije na strani odjemalca (brskalnik, mobilne naprave)
  • Življenjski čas žetona nastavite z expires_after.seconds in ga ohranite kratkega (300 sekund v uradnem primeru)
  • Priporočeni potek: vaše zaledje generira žeton, vaša sprednja stran pa ga posreduje kot podprotokol xai-client-secret. za vzpostavitev povezave WebSocket
  • Vedno načrtujte samodejno obnavljanje žetonov