Authentification et tokens éphémères

Deux méthodes d’authentification

L’API Voice Agent propose deux approches pour authentifier votre connexion WebSocket. Le choix dépend de l’architecture de votre application : côté serveur ou côté client.

Clé API directe (côté serveur)

La méthode la plus simple consiste à passer votre clé API dans le header d’autorisation lors de l’ouverture du WebSocket. Cette approche convient aux applications serveur où la clé reste protégée :

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-votre-cle-api"
  }
});

Cette méthode ne doit jamais être utilisée dans du code exécuté côté navigateur, car la clé API serait exposée dans le code source ou les outils de développement.

Tokens éphémères (côté client)

Pour les applications frontend (navigateur, application mobile), xAI propose un système de tokens éphémères. Votre serveur backend génère un token à durée limitée, que vous transmettez ensuite au client pour établir la connexion WebSocket.

La création d’un token se fait via une requête POST :

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

Le champ expires_after.seconds définit la durée de validité du token en secondes. L’exemple de la documentation officielle utilise 300 secondes (5 minutes) : un token éphémère est fait pour couvrir une session vocale, pas pour durer. Visez la durée la plus courte compatible avec vos sessions.

Architecture recommandée avec tokens éphémères

Voici le flux complet pour une application web :

// 1. Côté serveur (Node.js/Express) — génère le 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 } })
    }
  );
  // On renvoie tel quel le corps de la réponse xAI,
  // qui contient le token éphémère
  res.json(await response.json());
});

// 2. Côté client (navigateur) — utilise le token
// Le constructeur WebSocket du navigateur n'accepte pas de headers :
// le token passe en SOUS-PROTOCOLE, préfixé par « 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("Session vocale démarrée");
  };
}

Renouvellement des tokens

Lorsqu’un token expire, la connexion WebSocket est fermée par le serveur. Votre application doit surveiller cet événement et redemander un nouveau token à votre backend avant de reconnecter :

ws.onclose = async () => {
  // Token expiré ou connexion perdue : redemander un token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Bonnes pratiques de sécurité

Quelques règles essentielles pour sécuriser vos connexions :

• Ne jamais exposer votre clé API principale côté client
• Limiter la durée (expires_after.seconds) au strict nécessaire : si votre session moyenne dure cinq minutes, 300 à 600 secondes suffisent
• Valider les requêtes de token côté serveur (authentification utilisateur, rate limiting)
• Journaliser les créations de tokens pour détecter les usages anormaux
• Révoquer les tokens en cas de suspicion de compromission en faisant tourner (rotate) votre clé API principale

Points clés à retenir

• La clé API directe convient uniquement aux applications serveur
• Les tokens éphémères sont obligatoires pour les applications côté client (navigateur, mobile)
• La durée du token se règle via expires_after.seconds — gardez-la courte (300 s dans l’exemple officiel)
• Le flux recommandé : votre backend génère le token, votre frontend l’utilise en sous-protocole xai-client-secret. pour ouvrir le WebSocket
• Prévoyez toujours une logique de renouvellement automatique des tokens