Tokens éphémères pour les connexions WebSocket

Le problème : authentifier un client sans exposer votre clé

Lorsque vous développez une application avec une interface vocale ou temps réel utilisant l’API Grok, vous devez établir une connexion WebSocket directement depuis le navigateur ou le client mobile — les allers-retours par votre serveur ajouteraient une latence incompatible avec une conversation vocale fluide. Mais cette connexion directe pose un problème d’authentification : vous ne pouvez jamais inclure votre clé API dans du code côté client.

La raison est simple : toute clé présente dans du JavaScript frontend, dans une application mobile décompilable ou dans un binaire distribué doit être considérée comme compromise dès sa publication. N’importe quel utilisateur peut ouvrir les outils de développement de son navigateur et la lire. Pour sortir de ce dilemme, xAI propose les tokens éphémères : des jetons temporaires que le client peut utiliser sans jamais voir la clé maîtresse.

Le mécanisme des tokens éphémères

L’architecture repose sur un principe : la clé API ne quitte jamais votre serveur, et le client ne reçoit qu’un jeton à durée de vie courte. Le trajet complet est court. Le client commence par demander un token à votre backend, lequel appelle POST /v1/realtime/client_secrets avec votre clé API — cet appel est le seul endroit de la chaîne où la clé apparaît, et il se produit intégralement côté serveur. xAI retourne un token éphémère accompagné de sa date d’expiration, que votre backend transmet au client. Ce dernier n’a plus qu’à ouvrir la connexion WebSocket vers wss://api.x.ai/v1/realtime en présentant ce token. À aucun moment le navigateur n’a vu la clé maîtresse ; il a manipulé un jeton dont la valeur s’éteint d’elle-même.

L’appel de création, depuis votre backend, ressemble à ceci :

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}}'

Et la réponse :

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

Côté durée, vous disposez de trois repères : il n’existe pas de plancher documenté (quelques secondes sont possibles), la valeur par défaut est de 600 secondes (10 minutes), et le maximum est de 3600 secondes (1 heure).

Choisir la bonne durée

La durée du token doit correspondre à votre cas d’usage, et ce choix est une vraie décision de sécurité. Pour des interactions vocales ponctuelles — une question-réponse, une commande vocale, une dictée — une fenêtre de 300 à 600 secondes suffit largement : la session sera terminée bien avant l’expiration. Pour des conversations vocales soutenues comme un support client, un entretien ou une réunion assistée, visez 600 à 1800 secondes afin d’éviter une coupure en pleine conversation. Les sessions de travail prolongées — transcription en temps réel, monitoring vocal continu — peuvent justifier 1800 à 3600 secondes, mais utilisez la durée maximale avec précaution : elle élargit d’autant la fenêtre d’exploitation en cas de vol du token.

La règle d’or se résume ainsi : choisissez toujours la durée la plus courte compatible avec votre cas d’usage. Si un token est intercepté, une expiration à dix minutes transforme un incident potentiellement grave en désagrément mineur.

Implémentation backend

Voici un exemple de proxy sécurisé en Node.js :

// Route backend - NE PAS exposer côté client
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 });
});

Trois détails de cet exemple portent toute la sécurité du dispositif. La clé API vit dans une variable d’environnement serveur, jamais dans le code. Le middleware authenticateUser vérifie l’identité de l’utilisateur avant de délivrer un token — sans lui, n’importe qui pourrait obtenir des tokens et consommer votre quota à vos frais. Et seul le token éphémère, jamais la clé, est renvoyé au client.

Quelques pièges reviennent régulièrement dans les revues de code. La clé API glissée dans le frontend « juste pour le prototype » finit invariablement en production. Le token créé systématiquement avec la durée maximale, par confort, alors que le cas d’usage n’en demande pas le quart. L’endpoint de génération laissé sans vérification d’authentification, ouvert à tous. Et l’absence de gestion du renouvellement côté client, qui produit des erreurs d’expiration en pleine session au lieu d’une reconnexion transparente : puisque la réponse vous donne expires_at, votre client a tout ce qu’il faut pour demander un nouveau jeton avant l’échéance plutôt qu’après.

Points clés à retenir

• Les tokens éphémères permettent l’authentification WebSocket sans exposer votre clé API
• Endpoint : POST /v1/realtime/client_secrets (appel côté serveur uniquement)
• Durée configurable de quelques secondes à 3600 secondes maximum (défaut : 600s)
• Votre backend sert de proxy d’authentification entre le client et xAI
• Choisissez toujours la durée la plus courte compatible avec votre usage