Ephemere tokens voor WebSocket-verbindingen
Op deze pagina
Het probleem: een client verifiëren zonder uw sleutel bloot te geven
Wanneer u een spraak- of realtime-app bouwt met de Grok API, moet u rechtstreeks vanuit de browser of mobiele client een WebSocket-verbinding tot stand brengen. Verkeer via uw server routeren voegt latentie toe die vloeiende spraakgesprekken verstoort. Maar directe verbindingen creëren een authenticatieprobleem: u mag nooit uw API-sleutel opnemen in client-side code.
De reden is simpel: elke sleutel die is ingesloten in frontend JavaScript, een te decompileren mobiele app of een gedistribueerd binair bestand, is gecompromitteerd zodra u deze publiceert. Elke gebruiker kan de ontwikkelaarstools van zijn browser openen en de sleutel uitlezen. Om dit op te lossen, biedt xAI ephemere tokens: tijdelijke tokens die clients kunnen gebruiken zonder ooit de hoofdsleutel te zien.
Hoe ephemere tokens werken
De architectuur volgt één principe: de API-sleutel verlaat uw server nooit en de client ontvangt alleen een kortstondig token. De stroom is kort. De client vraagt een token aan bij uw backend, die POST /v1/realtime/client_secrets aanroept met uw API-sleutel. Deze aanroep is de enige plek waar de sleutel voorkomt, en dit gebeurt volledig server-side. xAI retourneert een ephemeer token met de vervaldatum, dat uw backend aan de client doorgeeft. De client opent vervolgens de WebSocket-verbinding naar wss://api.x.ai/v1/realtime en presenteert dit token. Op geen enkel moment ziet de browser de hoofdsleutel; deze werkt met een token dat automatisch verloopt.
De creatieaanroep vanaf uw backend ziet er als volgt uit:
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": 600}}'
En het antwoord:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Wat de duur betreft, zijn er drie ijkpunten: er is geen gedocumenteerde ondergrens (enkele seconden zijn mogelijk), de standaardwaarde is 600 seconden (10 minuten) en het maximum is 3600 seconden (1 uur).
De juiste duur kiezen
De tokenduur moet overeenkomen met uw use case; deze keuze is een echte beveiligingsbeslissing. Voor sporadische spraakinteracties—een vraag en antwoord, een spraakopdracht, dictatie—is een venster van 300 tot 600 seconden ruim voldoende: de sessie eindigt ruim voor het verstrijken van de termijn. Voor aanhoudende spraakgesprekken zoals klantenservice, een sollicitatiegesprek of een begeleid overleg, streeft u naar 600 tot 1800 seconden om te voorkomen dat het gesprek halverwege wordt afgebroken. Langdurige werksessies—realtime transcriptie, continue spraakmonitoring—kunnen 1800 tot 3600 seconden rechtvaardigen, maar gebruik de maximale duur met voorzichtigheid: dit vergroot het exploitatievenster als het token wordt gestolen.
De gouden regel luidt als volgt: kies altijd de kortste duur die compatibel is met uw use case. Als een token wordt onderschept, maakt een vervaltijd van tien minuten van een potentieel ernstig incident een kleine ergernis.
Backend-implementatie
Hier is een voorbeeld van een veilige proxy in Node.js:
// Backend route - DO NOT expose client-side
app.post("/api/realtime-token", authenticateUser, 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 }
})
}
);
const token = await response.json();
res.json({ token: token.value, expires_at: token.expires_at });
});
Drie details in dit voorbeeld dragen de volledige beveiliging van de opzet. De API-sleutel staat in een server-omgevingsvariabele, nooit in de code. De authenticateUser-middleware verifieert de identiteit van de gebruiker voordat een token wordt uitgegeven—zonder deze stap kan iedereen tokens verkrijgen en uw quota op uw kosten verbruiken. En alleen het ephemere token, nooit de sleutel, wordt teruggestuurd naar de client.
Enkele valkuilen komen regelmatig terug in code reviews. De API-sleutel die “alleen voor het prototype” in de frontend terechtkomt, belandt onvermijdelijk in productie. Het token dat systematisch met de maximale duur wordt aangemaakt, uit gemakzucht, terwijl de use case slechts een kwart daarvan vereist. Het generatie-endpoint dat zonder authenticatieverificatie wordt gelaten, open voor iedereen. En het ontbreken van hernieuwingsafhandeling aan de clientkant, wat leidt tot verloopfouten midden in een sessie in plaats van een transparante herverbinding: aangezien het antwoord u expires_at geeft, heeft uw client alles wat nodig is om vóór de deadline een nieuw token aan te vragen, in plaats van erna.
Belangrijkste punten
- Ephemere tokens maken WebSocket-authenticatie mogelijk zonder uw API-sleutel bloot te geven
- Endpoint:
POST /v1/realtime/client_secrets(uitsluitend server-side aanroep) - Configureerbare duur van enkele seconden tot maximaal 3600 seconden (standaard: 600s)
- Uw backend fungeert als een authenticatieproxy tussen de client en xAI
- Kies altijd de kortste duur die compatibel is met uw gebruik