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

Ephemeralni tokeni i sigurnost

Lekcija 13 od 14 Ažurirano 3. studenoga 2026. Srednja razina
Na ovoj stranici
  1. Problem s API ključem na klijentu
  2. Kako to funkcionira
  3. Arhitektura od kraja do kraja
  4. Pravila koja nikada ne smiješ prekršiti
  5. Ključne točke

Ažurirano 3. studenoga 2026., na temelju referencije xAI Voice API-ja. Izvori: Ephemeralni tokeni · Referenca Voice API-ja · Nastavak sesije.

Problem s API ključem na klijentu

Glasovna aplikacija koja se pokreće u pregledniku ili na mobitelu ne smije sadržavati tvoj API ključ. Svaki posjetitelj može otvoriti alate za programere, pročitati ključ iz JavaScript snopa ili zaglavlja zahtjeva, a zatim ga koristiti na tvom računu dok se tvoja kvota ne iscrpi. Nikakvo zamagljivanje koda ne može zaštititi vrijednost koju klijent mora imati kako bi pozvao API.

xAI-jevo rješenje su ephemeralni tokeni, nazvani i tajne klijenta: kratkotrajni token koji generira tvoj poslužitelj i koji ovlašćuje isključivo glasovnu sesiju, ništa više.

600s
zadani vijek trajanja
3600s
maksimalni vijek trajanja
POST
/v1/realtime/client_secrets
vrijednost
token, s expires_at

Kako to funkcionira

Tijek se svodi na pet koraka:

  1. Tvoj backend (sigurni poslužitelj) poziva POST /v1/realtime/client_secrets s tvojim API ključem
  2. API vraća privremeni token s ograničenim vijekom trajanja
  3. Tvoj backend šalje taj token klijentu (pregledniku ili mobilnoj aplikaciji)
  4. Klijent koristi token za povezivanje s Voice Agent WebSocketom
  5. Token istječe nakon vijeka trajanja koji si odabrao (expires_after.seconds)

Ono što može curiti na strani klijenta sada vrijedi znatno manje: token koji istječe unutar nekoliko minuta i može otvoriti samo glasovnu sesiju, a ne tvoj API ključ. Na poslužitelju generiranje traje nekoliko redaka koda. Primijeti da rukovatelj (handler) započinje provjerom korisnika: bez te provjere, tvoj backend postaje samo javni dispenser tokena.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Provjeri je li korisnik autentificiran
  if (!req.user) return res.status(401).json({ error: "Unauthorized" });

  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 }  // 10 minuta, zadana vrijednost
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

Klijent poznaje samo tvoju rutu: traži token, a zatim s njim otvara WebSocket.

// Frontend (preglednik)
async function startVoiceSession() {
  // Zatraži token od backenda
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Preglednički WebSocket ne prihvaća zaglavlja:
  // token ide u podprotokol, s prefiksom "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... konfiguracija sesije
}

Arhitektura od kraja do kraja

Sve zajedno, tijek započinje prijavom korisnika u tvoju aplikaciju. Njegov klijent zatim traži glasovni token od tvog backenda, a backend provjerava autentifikaciju i dopuštenja prije generiranja ephemeralnog tokena putem xAI API-ja. Token putuje natrag do klijenta, koji ga koristi za otvaranje sesije Voice Agenta, te automatski istječe na kraju svog vijeka trajanja.

Ta provjera između zahtjeva i generiranja pretvara jednostavan relej u kontrolnu točku, a upravo tu žive tvoja poslovna pravila. Možeš ograničiti broj glasovnih sesija po korisniku dnevno, tako da jedan račun ne može preko noći potrošiti tvoj mjesečni budžet. Možeš rezervirati tokene za aktivne pretplate, namećući svoj poslovni model negdje drugdje osim na sučelju. Možeš ograničiti broj zahtjeva (rate-limit), tako da neispravan ili zlonamjeran klijent ne može tražiti tisuću tokena u minuti. I možeš bilježiti svaki generirani token: to je tvoja jedina pouzdana osnova za nadzor, interno obračunavanje i analizu incidenata.

Pravila koja nikada ne smiješ prekršiti

API ključ nikada ne smije ići na klijent, ni u kojem obliku. Drži ga izvan front-end JavaScripta i izvan bilo koje varijable okruženja izložene izradi za preglednik (varijable s prefiksom za ubacivanje u snop završavaju javne). Drži ga izvan URL-ova, zapisnika (logova) i poruka o pogreškama koje se prikazuju korisnicima.

Zatim, zadrži vijek trajanja što kraćim koliko je praktično. Prema referenci API-ja, expires_after.seconds zadano iznosi 600 sekundi, a maksimum je 3.600; dokumentacija u svojim primjerima koristi 300. Iznad svega, token mora biti valjan kada klijent otvara vezu. Kratak vijek trajanja smanjuje prozor tijekom kojeg se presretnuti token može iskoristiti.

Dokumentacija ne navodi prekida li token koji istječe vezu koja je već otvorena. Ako se tvoj klijent mora ponovno povezati, nakon pada mreže ili tijekom vrlo duge sesije, zatraži novi token i koristi nastavak sesije: omogući resumption.enabled u session.update, zadrži ID koji primiš u conversation.created, a zatim ponovno otvori WebSocket s ?conversation_id=<id>. Prethodni razmjeni se reproduciraju, a model nastavlja tamo gdje je stao.

async function reconnect(conversationId) {
  const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
  const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
  const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
  ws.onopen = () => ws.send(JSON.stringify({
    type: "session.update",
    session: { resumption: { enabled: true } },  // pošalji ponovno pri svakom povezivanju
  }));
  return ws;
}

Za TTS u HTTP načinu rada, postoji još jednostavnija alternativa tokenima: proxy. Klijent šalje svoj tekst tvom backendu, a tvoj backend poziva TTS i vraća audio. Ključ nikada ne napušta tvoj poslužitelj, a dobivaš prirodno mjesto za filtriranje sadržaja i mjerenje korištenja usput.

Ključne točke

  • Ephemeralni tokeni osiguravaju pristup Voice Agentu iz aplikacija na strani klijenta
  • POST /v1/realtime/client_secrets vraća value i expires_at; expires_after.seconds zadano je 600, a maksimum 3.600
  • U pregledniku, token ide u podprotokol xai-client-secret.<token>
  • Tvoj backend mora provjeriti autentifikaciju i dopuštenja prije generiranja tokena
  • Nikada ne izlaži svoj API ključ na klijentu, u URL-ovima ili u zapisnicima
  • Za HTTP TTS, proksiranje kroz tvoj backend valjana je alternativa ephemeralnim tokenima