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. Le problème : vous ne pouvez jamais inclure votre clé API dans du code côté client.

Toute clé exposée dans du JavaScript frontend, une application mobile décompilable ou un binaire distribué est compromise. xAI propose une solution élégante : les tokens éphémères.

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

Architecture sécurisée

Le flux correct pour une application temps réel :

1. Le client demande un token à votre backend
2. Votre backend appelle POST /v1/realtime/client_secrets avec votre clé API (côté serveur)
3. xAI retourne un token éphémère avec une expiration
4. Votre backend transmet le token au client
5. Le client utilise ce token pour ouvrir la connexion WebSocket vers wss://api.x.ai/v1/realtime

Créer un token éphémère

L’appel depuis votre backend :

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

Réponse :

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

Paramètres de durée

• Minimum : quelques secondes (pas de plancher documenté)
• Par défaut : 600 secondes (10 minutes)
• Maximum : 3600 secondes (1 heure)

Bonnes pratiques de durée

La durée du token doit correspondre à votre cas d’usage :

Sessions courtes (300-600s)

Pour les interactions vocales ponctuelles : question-réponse, commande vocale, dictée.

Sessions moyennes (600-1800s)

Pour les conversations vocales soutenues : support client, entretien, réunion assistée.

Sessions longues (1800-3600s)

Pour les sessions de travail prolongées : transcription en temps réel, monitoring vocal continu. Utilisez la durée maximale avec précaution.

Règle d’or

Choisissez toujours la durée la plus courte compatible avec votre cas d’usage. Si un token est compromis, une expiration courte limite les dégâts.

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 });
});

Points importants dans cet exemple :

• La clé API est dans une variable d’environnement serveur
• Le middleware authenticateUser vérifie que l’utilisateur est authentifié
• Seul le token éphémère est envoyé au client

Erreurs fréquentes à éviter

• Clé API dans le code frontend : toute clé dans du JavaScript public est compromise
• Token avec durée maximale par défaut : ajustez la durée au cas d’usage réel
• Pas de vérification d’authentification : votre endpoint de génération de tokens doit vérifier l’identité de l’utilisateur
• Réutilisation de tokens expirés : gérez le renouvellement automatique côté client

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