Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Ephemere tokens en beveiliging

Les 13 van 14 Bijgewerkt op 3 november 2026 Gemiddeld
Op deze pagina
  1. Het probleem met een API-sleutel op de client
  2. Hoe het werkt
  3. De end-to-end architectuur
  4. Regels die u nooit mag overtreden
  5. Belangrijkste punten

Bijgewerkt op 3 november 2026, gebaseerd op de xAI Voice API-referentie. Bronnen: Ephemeral Tokens · Voice API-referentie · Session Resumption.

Het probleem met een API-sleutel op de client

Een spraak-app die in een browser of op een telefoon draait, kan uw API-sleutel niet meeleveren. Elke bezoeker kan de ontwikkelaarstools openen, de sleutel uitlezen uit de JavaScript-bundle of een request-header, en deze vervolgens op uw account gebruiken totdat uw quotum op is. Geen enkele vorm van obfuscatie beschermt een waarde die de client nodig heeft om de API aan te roepen.

xAI’s antwoord zijn ephemere tokens, ook wel client secrets genoemd: een kortstondig token, gegenereerd door uw server, dat uitsluitend een voicesessie autoriseert en niets anders.

600s
standaard levensduur
3600s
maximale levensduur
POST
/v1/realtime/client_secrets
waarde
het token, met expires_at

Hoe het werkt

De werkwijze komt neer op vijf stappen:

  1. Uw backend (een beveiligde server) roept POST /v1/realtime/client_secrets aan met uw API-sleutel
  2. De API retourneert een tijdelijk token met een beperkte levensduur
  3. Uw backend stuurt dat token naar de client (browser of mobiele app)
  4. De client gebruikt het token om verbinding te maken met de Voice Agent WebSocket
  5. Het token verloopt na de door u gekozen levensduur (expires_after.seconds)

Wat er aan de clientkant uitlekt, is nu veel minder waard: een token dat binnen enkele minuten verloopt en alleen een voicesessie kan openen, niet uw API-sleutel. Op de server duurt het genereren ervan slechts een paar regels code. Merk op dat de handler begint met het controleren van de gebruiker: zonder die controle is uw backend niets meer dan een publieke token-automaat.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Controleer of de gebruiker geauthenticeerd is
  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 minuten, de standaardwaarde
      })
    }
  );

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

De client kent alleen uw eigen route: deze vraagt een token aan en opent vervolgens de WebSocket daarmee.

// Frontend (browser)
async function startVoiceSession() {
  // Vraag de backend om een token
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // De browser-WebSocket accepteert geen headers:
  // het token gaat in een subprotocol, voorafgegaan door "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... sessieconfiguratie
}

De end-to-end architectuur

Samengevat begint de flow met de gebruiker die inlogt op uw app. De client vraagt vervolgens uw backend om een voice-token, en de backend controleert authenticatie en rechten voordat het ephemere token via de xAI-API wordt gegenereerd. Het token reist terug naar de client, die het gebruikt om de Voice Agent-sessie te openen, en het verloopt automatisch aan het einde van zijn levensduur.

Die controle tussen het verzoek en de generatie maakt van een simpele relay een controlepunt, en daar leven uw bedrijfsregels. U kunt het aantal voicesessies per gebruiker per dag beperken, zodat één account uw maandbudget niet in één nacht opsoupeert. U kunt tokens reserveren voor actieve abonnementen, waardoor u uw bedrijfsmodel ergens anders dan in de interface afdwingt. U kunt verzoeken rate-limieten, zodat een buggy of kwaadwillende client niet duizend tokens per minuut kan aanvragen. En u kunt elk gegenereerd token loggen: het is uw enige betrouwbare basis voor monitoring, interne facturatie en incidentanalyse.

Regels die u nooit mag overtreden

De API-sleutel gaat nooit naar de client, in welke vorm dan ook. Houd deze uit front-end JavaScript en uit elke omgevingsvariabele die wordt blootgesteld aan de browser-build (variabelen die zijn voorvoegd om in de bundle te worden geïnjecteerd, worden uiteindelijk openbaar). Houd deze ook uit URL’s, logs en foutberichten die aan gebruikers worden getoond.

Houd vervolgens de levensduur zo kort als praktisch mogelijk is. Volgens de API-referentie is de standaardwaarde voor expires_after.seconds 600 seconden en het maximum 3.600; de documentatie gebruikt 300 in zijn voorbeelden. Bovenal moet het token geldig zijn wanneer de client de verbinding opent. Een korte levensduur verkleint het venster waarin een onderschept token kan worden gebruikt.

De documentatie vermeldt niet of een verlopen token een reeds geopende verbinding verbreekt. Als uw client opnieuw verbinding moet maken, na een netwerkonderbreking of tijdens een zeer lange sessie, vraag dan een nieuw token aan en gebruik session resumption: schakel resumption.enabled in bij session.update, bewaar de ID die u ontvangt in conversation.created, en open de WebSocket opnieuw met ?conversation_id=<id>. De eerdere beurten worden afgespeeld en het model gaat verder waar het gebleven was.

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 } },  // opnieuw verzenden bij elke verbinding
  }));
  return ws;
}

Voor TTS in HTTP-modus is er een nog eenvoudiger alternatief voor tokens: een proxy. De client stuurt zijn tekst naar uw backend, en uw backend roept TTS aan en retourneert de audio. De sleutel verlaat uw server nooit, en u krijgt een natuurlijke plek om inhoud te filteren en gebruik te meten onderweg.

Belangrijkste punten

  • Ephemere tokens beveiligen de toegang tot de Voice Agent vanuit client-side apps
  • POST /v1/realtime/client_secrets retourneert value en expires_at; expires_after.seconds heeft standaardwaarde 600 en maximum 3.600
  • In de browser gaat het token in het subprotocol xai-client-secret.<token>
  • Uw backend moet authenticatie en rechten controleren voordat een token wordt gegenereerd
  • Stel uw API-sleutel nooit bloot op de client, in URL’s of in logs
  • Voor HTTP-TTS is proxying via uw backend een geldig alternatief voor ephemere tokens