Authenticatie en ephemeral tokens
Op deze pagina
Twee manieren om te authenticeren
De Voice Agent API biedt twee methoden om uw WebSocket-verbinding te authenticeren. De keuze hangt af van waar uw code draait: op de server of op de client.
Directe API-sleutel (serverzijde)
De eenvoudigste methode is het doorgeven van uw API-sleutel in de autorisatieheader bij het openen van de WebSocket. Dit werkt voor servertoepassingen, waar de sleutel beschermd blijft:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Gebruik deze methode nooit in code die in de browser draait: de API-sleutel zou dan zichtbaar worden in de broncode of de ontwikkelaarstools.
Ephemeral tokens (clientzijde)
Voor front-end applicaties (browser, mobiel) biedt xAI ephemeral tokens. Uw backend genereert een kortstondig token, dat u vervolgens aan de client doorgeeft om de WebSocket-verbinding tot stand te brengen.
U maakt een token aan met een POST-request:
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}}'
Het veld expires_after.seconds bepaalt hoe lang het token geldig is, in seconden. Het voorbeeld in de officiële documentatie gebruikt 300 seconden (5 minuten): een ephemeral token is bedoeld om een voicesessie te overbruggen, niet om lang mee te gaan. Streef naar de kortst mogelijke levensduur die voor uw sessies werkt.
Aanbevolen architectuur met ephemeral tokens
Hieronder ziet u de volledige flow voor een webapplicatie:
// 1. Serverzijde (Node.js/Express): genereer het token
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 } })
}
);
// Geef de response body van xAI onveranderd terug;
// deze bevat het ephemeral token
res.json(await response.json());
});
// 2. Clientzijde (browser): gebruik het token
// De WebSocket-constructor van de browser accepteert geen headers:
// het token gaat in een SUBPROTOCOL, voorafgegaan door "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");
};
}
Tokens vernieuwen
De documentatie vermeldt niet of een verlopen token een reeds geopende verbinding sluit. Hoe dan ook, uw applicatie heeft een plan nodig voor het geval de verbinding wordt verbroken: luister naar de close-event, vraag uw backend om een nieuw token en maak opnieuw verbinding:
ws.onclose = async () => {
// Verbinding verbroken of gesloten: vraag een nieuw token aan
const newToken = await fetchNewToken();
reconnect(newToken);
};
Best practices voor beveiliging
Enkele essentiële regels houden uw verbindingen veilig:
- Stel uw hoofd-API-sleutel nooit bloot op de client
- Houd de levensduur (
expires_after.seconds) zo kort mogelijk: als uw gemiddelde sessie vijf minuten duurt, volstaan 300 tot 600 seconden - Valideer token-aanvragen op de server (gebruikersauthenticatie, rate limiting)
- Log het aanmaken van tokens om abnormaal gebruik op te sporen
- Roteer uw hoofd-API-sleutel als u vermoedt dat deze is gecompromitteerd
Belangrijkste punten
- Een directe API-sleutel is alleen geschikt voor servertoepassingen
- Ephemeral tokens zijn onmisbaar voor client-side apps (browser, mobiel)
- Stel de levensduur van het token in met
expires_after.secondsen houd deze kort (300 seconden in het officiële voorbeeld) - De aanbevolen flow: uw backend genereert het token en uw front-end geeft dit door als het
xai-client-secret.subprotocol om de WebSocket te openen - Voorzie altijd in automatische tokenvernieuwing