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 '{"ttl": 3600}'

Le paramètre ttl (Time To Live) définit la durée de validité du token en secondes. La valeur maximale est de 3600 secondes (1 heure), et la valeur par défaut est de 600 secondes (10 minutes).

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({ ttl: 1800 })
    }
  );
  const data = await response.json();
  res.json({ token: data.client_secret });
});

// 2. Côté client (navigateur) — utilise le token
async function startVoiceSession() {
  const res = await fetch("/api/realtime-token", { method: "POST" });
  const { token } = await res.json();

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

  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 (event) => {
  if (event.code === 1008) {
    // Token expiré — renouveler
    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 le TTL au strict nécessaire (si votre session moyenne dure 5 minutes, un TTL de 600 secondes suffit)
• 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)
• Un token éphémère a une durée maximale de 3600 secondes (1 heure)
• Le flux recommandé : votre backend génère le token, votre frontend l’utilise pour ouvrir le WebSocket
• Prévoyez toujours une logique de renouvellement automatique des tokens