Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Autentifikacija i privremeni tokeni

Lekcija 2 od 16 Ažurirano 30. srpnja 2026. Programer
Na ovoj stranici
  1. Dva načina autentifikacije
  2. Preporučena arhitektura s privremenim tokenima
  3. Najbolje sigurnosne prakse
  4. Ključne točke

Dva načina autentifikacije

Voice Agent API nudi dva načina autentifikacije tvoje WebSocket veze. Koji ćeš odabrati ovisi o tome gdje se tvoj kod izvršava: na poslužitelju ili na klijentu.

Izravni API ključ (strana poslužitelja)

Najjednostavnija metoda je prosljeđivanje tvog API ključa u zaglavlju za autorizaciju prilikom otvaranja WebSocket veze. Ovo funkcionira za aplikacije na poslužitelju, gdje ključ ostaje zaštićen:

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

Nikada ne koristi ovu metodu u kodu koji se izvršava u pregledniku: API ključ bi bio izložen u izvornom kodu ili alatima za programere.

Privremeni tokeni (strana klijenta)

Za front-end aplikacije (preglednik, mobilni uređaji), xAI pruža privremene tokene. Tvoj backend generira kratkotrajni token koji zatim prosljeđuješ klijentu za uspostavu WebSocket veze.

Token stvaraš POST zahtjevom:

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 određuje koliko je dugo token valjan, u sekundama. Primjer u službenoj dokumentaciji koristi 300 sekundi (5 minuta): privremeni token namijenjen je pokrivanju glasovne sesije, a ne dugotrajnom korištenju. Ciljaj na najkraći mogući vijek trajanja koji odgovara tvojim sesijama.

Preporučena arhitektura s privremenim tokenima

Evo cjelokupnog tijeka za web aplikaciju:

// 1. Strana poslužitelja (Node.js/Express): generiranje tokena
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 } })
    }
  );
  // Vrati tijelo odgovora od xAI-a kakvo jest;
  // ono sadrži privremeni token
  res.json(await response.json());
});

// 2. Strana klijenta (preglednik): korištenje tokena
// WebSocket konstruktor u pregledniku ne prihvaća zaglavlja:
// token se šalje kao SUBPROTOCOL, s prefiksom "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 tokena

Dokumentacija ne navodi zatvara li istek tokena već uspostavljenu vezu. U svakom slučaju, tvoja aplikacija mora imati plan za slučaj prekida veze: prati događaj zatvaranja, zatraži novi token od svog backenda, a zatim se ponovno poveži:

ws.onclose = async () => {
  // Veza je izgubljena ili zatvorena: zatraži novi token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Najbolje sigurnosne prakse

Nekoliko ključnih pravila osigurat će sigurnost tvojih veza:

  • Nikada ne izlaži svoj glavni API ključ na klijentskoj strani
  • Zadrži vijek trajanja (expires_after.seconds) što je kraće moguće: ako tvoja prosječna sesija traje pet minuta, 300 do 600 sekundi je dovoljno
  • Validiraj zahtjeve za token na poslužitelju (autentifikacija korisnika, ograničavanje stope zahtjeva)
  • Bilježi stvaranje tokena kako bi mogao uočiti neobičnu upotrebu
  • Rotiraj svoj glavni API ključ ako sumnjaš da je kompromitiran

Ključne točke

  • Izravni API ključ prikladan je samo za aplikacije na poslužitelju
  • Privremeni tokeni su nužni za aplikacije na strani klijenta (preglednik, mobilni uređaji)
  • Postavi vijek trajanja tokena pomoću expires_after.seconds i zadrži ga kratkim (300 sekundi u službenom primjeru)
  • Preporučeni tijek: tvoj backend generira token, a tvoj front-end ga prosljeđuje kao podprotokol xai-client-secret. za otvaranje WebSocket veze
  • Uvijek planiraj automatsko obnavljanje tokena