Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Ephemere Tokens und Sicherheit

Lektion 13 von 14 Aktualisiert am 3. November 2026 Mittelstufe
Auf dieser Seite
  1. Das Problem mit einem API-Schlüssel auf dem Client
  2. Funktionsweise
  3. Die End-to-End-Architektur
  4. Regeln, die Sie niemals verletzen dürfen
  5. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf der xAI Voice API-Referenz. Quellen: Ephemere Tokens · Voice API-Referenz · Sitzungswiederherstellung.

Das Problem mit einem API-Schlüssel auf dem Client

Eine Voice-Anwendung, die in einem Browser oder auf einem Smartphone läuft, kann Ihren API-Schlüssel nicht mitliefern. Jeder Besucher kann die Entwicklertools öffnen, den Schlüssel aus dem JavaScript-Bundle oder einem Anforderungs-Header auslesen und ihn dann auf Ihrem Konto verwenden, bis Ihr Kontingent erschöpft ist. Keine Menge an Verschleierung schützt einen Wert, den der Client besitzen muss, um die API aufzurufen.

Die Antwort von xAI sind ephemere Tokens, auch als Client-Geheimnisse bezeichnet: ein kurzlebiges Token, das von Ihrem Server generiert wird und eine Voice-Sitzung autorisiert, aber nichts anderes.

600s
Standardlebensdauer
3600s
maximale Lebensdauer
POST
/v1/realtime/client_secrets
Wert
das Token mit expires_at

Funktionsweise

Der Ablauf lässt sich auf fünf Schritte reduzieren:

  1. Ihr Backend (ein sicherer Server) ruft POST /v1/realtime/client_secrets mit Ihrem API-Schlüssel auf
  2. Die API gibt ein vorübergehendes Token mit begrenzter Lebensdauer zurück
  3. Ihr Backend sendet dieses Token an den Client (Browser oder mobile App)
  4. Der Client verwendet das Token, um sich mit dem Voice-Agent WebSocket zu verbinden
  5. Das Token erlischt nach der von Ihnen gewählten Lebensdauer (expires_after.seconds)

Was auf der Client-Seite auslecken kann, ist nun deutlich weniger wertvoll: ein Token, das innerhalb weniger Minuten abläuft und nur eine Voice-Sitzung öffnen kann, nicht aber Ihren API-Schlüssel. Auf dem Server dauert die Generierung eines solchen Tokens nur wenige Zeilen Code. Beachten Sie, dass der Handler zunächst den Benutzer überprüft: Ohne diese Prüfung wäre Ihr Backend lediglich ein öffentlicher Token-Verteiler.

// Node.js Backend (Express)
app.post("/api/voice-token", async (req, res) => {
  // Prüfen, ob der Benutzer authentifiziert ist
  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, der Standardwert
      })
    }
  );

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

Der Client kennt nur Ihre eigene Route: Er fordert ein Token an und öffnet dann den WebSocket mit diesem Token.

// Frontend (Browser)
async function startVoiceSession() {
  // Beim Backend nach einem Token fragen
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Der Browser WebSocket akzeptiert keine Header:
  // das Token geht in einem Subprotokoll, vorangestellt mit "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... Sitzungs konfigurieren
}

Die End-to-End-Architektur

Zusammengefasst beginnt der Ablauf damit, dass der Benutzer sich in Ihrer App anmeldet. Anschließend fragt sein Client beim Backend nach einem Voice-Token, und das Backend prüft Authentifizierung und Berechtigungen, bevor es das ephemere Token über die xAI-API generiert. Das Token reist zurück zum Client, der es verwendet, um die Voice-Agent-Sitzung zu öffnen, und es erlischt automatisch am Ende seiner Lebensdauer.

Diese Prüfung zwischen der Anforderung und der Generierung verwandelt eine einfache Weiterleitung in einen Kontrollpunkt, und hier leben Ihre Geschäftsregeln. Sie können die Anzahl der Voice-Sitzungen pro Benutzer pro Tag begrenzen, sodass ein einzelnes Konto nicht über Nacht Ihr monatliches Budget aufbrauchen kann. Sie können Tokens für aktive Abonnements reservieren und damit Ihr Geschäftsmodell an einer Stelle durchsetzen, die nicht die Benutzeroberfläche ist. Sie können Anfragen rate-limiten, sodass ein fehlerhafter oder bösartiger Client nicht pro Minute tausend Tokens anfordern kann. Und Sie können jedes generierte Token protokollieren: Dies ist Ihre einzige verlässliche Grundlage für Überwachung, interne Abrechnung und die Analyse von Vorfällen.

Regeln, die Sie niemals verletzen dürfen

Der API-Schlüssel geht niemals an den Client, in irgendeiner Form. Halten Sie ihn aus dem Frontend-JavaScript und aus jeder Umgebungsvariablen heraus, die dem Browser-Build ausgesetzt ist (Variablen, die mit einem Präfix versehen werden, um in das Bundle injiziert zu werden, enden öffentlich). Halten Sie ihn auch aus URLs, Protokollen und Fehlermeldungen heraus, die Benutzern angezeigt werden.

Als Nächstes halten Sie die Lebensdauer so kurz wie praktikabel. Gemäß der API-Referenz beträgt expires_after.seconds der Standardwert 600 Sekunden und das Maximum 3.600; die Dokumentation verwendet in ihren Beispielen 300. Vor allem muss das Token gültig sein, wenn der Client die Verbindung öffnet. Eine kurze Lebensdauer verkleinert das Zeitfenster, in dem ein abgefangenes Token verwendet werden kann.

Die Dokumentation sagt nicht, ob ein ablaufendes Token eine bereits offene Verbindung unterbricht. Wenn Ihr Client neu verbinden muss, nach einem Netzwerkausfall oder während einer sehr langen Sitzung, fordern Sie ein neues Token an und verwenden Sie Sitzungswiederherstellung: Aktivieren Sie resumption.enabled in session.update, behalten Sie die ID, die Sie in conversation.created erhalten, und öffnen Sie den WebSocket erneut mit ?conversation_id=<id>. Die vorherigen Runden werden wiederholt, und das Modell setzt dort fort, wo es aufgehört hat.

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 } },  // erneut senden bei jeder Verbindung
  }));
  return ws;
}

Für TTS im HTTP-Modus gibt es eine noch einfachere Alternative zu Tokens: ein Proxy. Der Client sendet seinen Text an Ihr Backend, und Ihr Backend ruft TTS auf und gibt den Audioinhalt zurück. Der Schlüssel verlässt Ihren Server nie, und Sie erhalten einen natürlichen Ort, um Inhalte zu filtern und die Nutzung zu meteren.

Kernaussagen

  • Ephemere Tokens sichern den Zugriff auf den Voice-Agent von Client-seitigen Anwendungen aus
  • POST /v1/realtime/client_secrets gibt value und expires_at zurück; expires_after.seconds beträgt der Standardwert 600 und das Maximum 3.600
  • Im Browser geht das Token in das Subprotokoll xai-client-secret.<token>
  • Ihr Backend muss Authentifizierung und Berechtigungen prüfen, bevor es ein Token generiert
  • Stellen Sie Ihren API-Schlüssel niemals auf dem Client, in URLs oder in Protokollen zur Verfügung
  • Für HTTP-TTS ist das Proxying über Ihr Backend eine gültige Alternative zu ephemeren Tokens