Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Ephemere tokens og sikkerhed

Lektion 13 af 14 Opdateret 3. november 2026 Mellem
På denne side
  1. Problemet med en API-nøgle på klienten
  2. Sådan fungerer det
  3. Den end-to-end arkitektur
  4. Regler du aldrig må bryde
  5. Vigtige pointer

Opdateret 3. november 2026 baseret på xAI Voice API-referencen. Kilder: Ephemeral Tokens · Voice API-reference · Session Resumption.

Problemet med en API-nøgle på klienten

En tale-app, der kører i en browser eller på en telefon, kan ikke medsende din API-nøgle. Enhver besøgende kan åbne udviklerværktøjerne, læse nøglen fra JavaScript-bundtet eller en anmodningsheader og derefter bruge den på din konto, indtil din kvote er opbrugt. Ingen mængde af sløring beskytter en værdi, som klienten skal have for at kunne kalde API’et.

xAIs svar er ephemere tokens, også kaldet klient-hemmeligheder: et kortlivet token, genereret af din server, der autoriserer en talesession og intet andet.

600s
standard levetid
3600s
maksimal levetid
POST
/v1/realtime/client_secrets
værdi
tokennet med expires_at

Sådan fungerer det

Flowet reduceres til fem trin:

  1. Din backend (en sikker server) kalder POST /v1/realtime/client_secrets med din API-nøgle.
  2. API’et returnerer et midlertidigt token med en begrænset levetid.
  3. Din backend sender dette token til klienten (browser eller mobilapp).
  4. Klienten bruger tokennet til at oprette forbindelse til Voice Agent WebSocket.
  5. Tokennet udløber efter den levetid, du har valgt (expires_after.seconds).

Det, der kan lække på klientsiden, er nu langt mindre værd: et token, der udløber inden for få minutter, og som kun kan åbne en talesession, ikke din API-nøgle. På serveren tager genereringen af et token kun få linjer kode. Bemærk, at handleren starter med at tjekke brugeren: uden dette tjek er din backend blot en offentlig token-dispenser.

// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Tjek at brugeren er autentificeret
  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 minutter, standardværdien
      })
    }
  );

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

Klienten kender kun din egen rute: den anmoder om et token og åbner derefter WebSocket-forbindelsen med det.

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

  // Browserens WebSocket accepterer ikke headers:
  // tokennet sendes i en subprotocol med præfikset "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... session konfiguration
}

Den end-to-end arkitektur

Samlet set starter flowet med, at brugeren logger ind på din app. Deres klient anmoder derefter din backend om et tale-token, og backend’en tjekker autentificering og tilladelser, før det ephemere token genereres via xAI API’et. Tokennet rejser tilbage til klienten, som bruger det til at åbne Voice Agent-sessionen, og det udløber automatisk ved slutningen af sin levetid.

Dette tjek mellem anmodningen og genereringen omdanner en simpel relæfunktion til et kontrolpunkt, og det er her, dine forretningsregler lever. Du kan sætte loft over antallet af talesessioner pr. bruger pr. dag, så en enkelt konto ikke kan brænde dit månedlige budget af over natten. Du kan reservere tokens til aktive abonnementer og håndhæve din forretningsmodel et andet sted end i grænsefladen. Du kan rate-begrænse anmodninger, så en fejlbehæftet eller ondsindet klient ikke kan anmode om tusind tokens i minuttet. Og du kan logge hvert eneste token, du genererer: det er dit eneste pålidelige grundlag for overvågning, intern fakturering og hændelsesanalyse.

Regler du aldrig må bryde

API-nøglen sendes aldrig til klienten, i nogen form. Hold den væk fra front-end JavaScript og væk fra alle miljøvariabler, der eksponeres for browser-buildet (variabler med præfiks til injicering i bundtet ender offentligt tilgængelige). Hold den også væk fra URL’er, logs og fejlmeddelelser, der vises til brugere.

Hold derefter levetiden så kort som praktisk muligt. Ifølge API-referencen er standardværdien for expires_after.seconds 600 sekunder med et maksimum på 3.600; dokumentationen bruger 300 i sine eksempler. Frem for alt skal tokennet være gyldigt, når klienten åbner forbindelsen. En kort levetid indskrænker det tidsrum, hvor et aflyttet token kan bruges.

Dokumentationen siger ikke, om et udløbende token afbryder en forbindelse, der allerede er åben. Hvis din klient har brug for at genoprette forbindelsen efter et netværksudfald eller under en meget lang session, skal du anmode om et nyt token og bruge session resumption: aktiver resumption.enabled i session.update, behold ID’et, du modtager i conversation.created, og genåbn derefter WebSocket med ?conversation_id=<id>. De tidligere ture afspilles igen, og modellen fortsætter, hvor den slap.

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 } },  // send igen ved hver forbindelse
  }));
  return ws;
}

Til TTS i HTTP-tilstand findes der en endnu simplere alternativ løsning til tokens: en proxy. Klienten sender sin tekst til din backend, og din backend kalder TTS og returnerer lyden. Nøglen forlader aldrig din server, og du får et naturligt sted at filtrere indhold og måle forbrug undervejs.

Vigtige pointer

  • Ephemere tokens sikrer adgangen til Voice Agent fra klient-side apps
  • POST /v1/realtime/client_secrets returnerer value og expires_at; expires_after.seconds har standardværdien 600 og maksimum 3.600
  • I browseren placeres tokennet i subprotokollen xai-client-secret.<token>
  • Din backend skal tjekke autentificering og tilladelser, før et token genereres
  • Eksponér aldrig din API-nøgle på klienten, i URL’er eller i logs
  • Til HTTP TTS er proxying gennem din backend et gyldigt alternativ til ephemere tokens