Authentifizierung und temporäre Tokens
Auf dieser Seite
Zwei Authentifizierungsmethoden
Die Voice Agent API bietet zwei Möglichkeiten zur Authentifizierung Ihrer WebSocket-Verbindung. Die Wahl hängt davon ab, wo Ihr Code ausgeführt wird: auf dem Server oder auf dem Client.
Direkter API-Schlüssel (Serverseite)
Die einfachste Methode besteht darin, Ihren API-Schlüssel im Autorisierungs-Header zu übermitteln, wenn Sie die WebSocket-Verbindung herstellen. Dies funktioniert für Serveranwendungen, bei denen der Schlüssel geschützt bleibt:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Verwenden Sie diese Methode niemals in Code, der im Browser ausgeführt wird: Der API-Schlüssel wäre im Quellcode oder in den Entwicklertools exponiert.
Temporäre Tokens (Clientseite)
Für Frontend-Anwendungen (Browser, Mobile) stellt xAI temporäre Tokens bereit. Ihr Backend generiert ein kurzlebiges Token, das Sie dann an den Client übergeben, um die WebSocket-Verbindung herzustellen.
Sie erstellen ein Token mit einer POST-Anfrage:
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}}'
Das Feld expires_after.seconds legt fest, wie lange das Token gültig ist, in Sekunden. Das Beispiel in der offiziellen Dokumentation verwendet 300 Sekunden (5 Minuten): Ein temporäres Token soll eine Sprachsession abdecken, nicht länger bestehen. Streben Sie die kürzeste Lebensdauer an, die für Ihre Sessions funktioniert.
Empfohlene Architektur mit temporären Tokens
Hier ist der vollständige Ablauf für eine Webanwendung:
// 1. Serverseite (Node.js/Express): Token generieren
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 } })
}
);
// Geben Sie den xAI-Antwortkörper unverändert zurück;
// er enthält das temporäre Token
res.json(await response.json());
});
// 2. Clientseite (Browser): Token verwenden
// Der WebSocket-Konstruktor des Browsers akzeptiert keine Header:
// Das Token wird im SUBPROTOCOL übergeben, vorangestellt mit "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("Sprachsession gestartet");
};
}
Erneuerung von Tokens
Die Dokumentation gibt nicht an, ob ein ablaufendes Token eine bereits offene Verbindung schließt. In jedem Fall benötigt Ihre Anwendung einen Plan für den Fall, dass die Verbindung abbricht: Beobachten Sie das Close-Event, bitten Sie Ihr Backend um ein neues Token und verbinden Sie sich erneut:
ws.onclose = async () => {
// Verbindung verloren oder geschlossen: neues Token anfordern
const newToken = await fetchNewToken();
reconnect(newToken);
};
Best Practices für die Sicherheit
Einige wesentliche Regeln halten Ihre Verbindungen sicher:
- Exponieren Sie niemals Ihren Haupt-API-Schlüssel auf dem Client
- Halten Sie die Lebensdauer (
expires_after.seconds) so kurz wie möglich: Wenn Ihre durchschnittliche Session fünf Minuten dauert, reichen 300 bis 600 Sekunden - Validieren Sie Token-Anfragen auf dem Server (Benutzerauthentifizierung, Rate Limiting)
- Loggen Sie die Token-Erstellung, um ungewöhnliche Nutzung zu erkennen
- Rotieren Sie Ihren Haupt-API-Schlüssel, wenn Sie vermuten, dass er kompromittiert wurde
Kernaussagen
- Ein direkter API-Schlüssel ist nur für Serveranwendungen geeignet
- Temporäre Tokens sind für Clientseitige Anwendungen (Browser, Mobile) unerlässlich
- Stellen Sie die Token-Lebensdauer mit
expires_after.secondsein und halten Sie sie kurz (300 Sekunden im offiziellen Beispiel) - Der empfohlene Ablauf: Ihr Backend generiert das Token, und Ihr Frontend überreicht es als
xai-client-secret.-Subprotokoll, um die WebSocket-Verbindung herzustellen - Planen Sie immer die automatische Token-Erneuerung vor