Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Godkendelse og engangstokens

Lektion 2 af 16 Opdateret 30. juli 2026 Udvikler
På denne side
  1. To måder at godkende på
  2. Anbefalet arkitektur med engangstokens
  3. Bedste praksis for sikkerhed
  4. Vigtige pointer

To måder at godkende på

Voice Agent API tilbyder to måder at godkende din WebSocket-forbindelse på. Hvilken du vælger, afhænger af, hvor din kode kører: på serveren eller på klienten.

Direkte API-nøgle (server-side)

Den enkleste metode er at sende din API-nøgle i autorisationsheadere, når du åbner WebSocket-forbindelsen. Dette fungerer til serverapplikationer, hvor nøglen forbliver beskyttet:

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

Brug aldrig denne metode i kode, der kører i browseren: API-nøglen ville blive eksponeret i kildekoden eller udviklerværktøjerne.

Engangstokens (klient-side)

Til front-end-applikationer (browser, mobil) leverer xAI engangstokens. Din backend genererer et kortlivet token, som du derefter sender til klienten for at åbne WebSocket-forbindelsen.

Du opretter et token med en POST-anmodning:

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}}'

Feltet expires_after.seconds angiver, hvor længe tokenet er gyldigt, målt i sekunder. Eksemplet i den officielle dokumentation bruger 300 sekunder (5 minutter): et engangstoken er beregnet til at dække en talesession, ikke til at vare ved. Sig efter den korteste levetid, der fungerer for dine sessioner.

Anbefalet arkitektur med engangstokens

Her er det komplette flow til en webapplikation:

// 1. Server-side (Node.js/Express): generér tokenet
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 } })
    }
  );
  // Returnér xAI-svarets body uændret;
  // det indeholder engangstokenet
  res.json(await response.json());
});

// 2. Klient-side (browser): brug tokenet
// Browserens WebSocket-konstruktør accepterer ikke headers:
// tokenet sendes i en SUBPROTOCOL med præfikset "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");
  };
}

Fornyelse af tokens

Dokumentationen specificerer ikke, om et udløbende token lukker en forbindelse, der allerede er åben. Uanset hvad har din app brug for en plan til, når forbindelsen afbrydes: overvåg close-begivenheden, anmod din backend om et nyt token, og genopret derefter forbindelsen:

ws.onclose = async () => {
  // Forbindelse tabt eller lukket: anmod om et nyt token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Bedste praksis for sikkerhed

Nogle få essentielle regler holder dine forbindelser sikre:

  • Eksponér aldrig din hoved-API-nøgle på klienten
  • Hold levetiden (expires_after.seconds) så kort som muligt: hvis din gennemsnitlige session varer fem minutter, er 300 til 600 sekunder nok
  • Valider token-anmodninger på serveren (brugerautentificering, rate limiting)
  • Log oprettelse af tokens, så du kan spotte unormal brug
  • Rotér din hoved-API-nøgle, hvis du har mistanke om, at den er blevet kompromitteret

Vigtige pointer

  • En direkte API-nøgle er kun egnet til serverapplikationer
  • Engangstokens er et must til klient-side-applikationer (browser, mobil)
  • Indstil tokenets levetid med expires_after.seconds og hold den kort (300 sekunder i det officielle eksempel)
  • Det anbefalede flow: din backend genererer tokenet, og din front-end sender det som xai-client-secret.-underprotokollen for at åbne WebSocket-forbindelsen
  • Planlæg altid automatisk fornyelse af tokens