Ir al contenido principal
Español— Elegir un idioma
Menú

Autenticación y tokens efímeros

Lección 2 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Dos formas de autenticarse
  2. Arquitectura recomendada con tokens efímeros
  3. Mejores prácticas de seguridad
  4. Puntos clave

Dos formas de autenticarse

La API de Voice Agent ofrece dos métodos para autenticar tu conexión WebSocket. El que elijas depende de dónde se ejecute tu código: en el servidor o en el cliente.

Clave de API directa (lado del servidor)

El método más sencillo consiste en pasar tu clave de API en la cabecera de autorización al abrir el WebSocket. Esto funciona para aplicaciones de servidor, donde la clave permanece protegida:

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

Nunca utilices este método en código que se ejecute en el navegador: la clave de API quedaría expuesta en el código fuente o en las herramientas de desarrollo.

Tokens efímeros (lado del cliente)

Para aplicaciones de front-end (navegador, móvil), xAI proporciona tokens efímeros. Tu backend genera un token de corta duración que luego pasas al cliente para establecer la conexión WebSocket.

Creas un token mediante una solicitud 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}}'

El campo expires_after.seconds define la validez del token en segundos. El ejemplo de la documentación oficial utiliza 300 segundos (5 minutos): un token efímero está diseñado para cubrir una sesión de voz, no para perdurar. Apunta a la vida útil más corta posible que funcione para tus sesiones.

Arquitectura recomendada con tokens efímeros

Este es el flujo completo para una aplicación web:

// 1. Lado del servidor (Node.js/Express): generar el 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 } })
    }
  );
  // Devolver el cuerpo de la respuesta de xAI tal cual;
  // contiene el token efímero
  res.json(await response.json());
});

// 2. Lado del cliente (navegador): usar el token
// El constructor WebSocket del navegador no acepta cabeceras:
// el token va en un SUBPROTOCOLO, con el prefijo "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("Sesión de voz iniciada");
  };
}

Renovación de tokens

La documentación no especifica si un token que caduca cierra una conexión ya establecida. En cualquier caso, tu aplicación necesita un plan para cuando la conexión se interrumpa: escucha el evento de cierre, solicita un nuevo token a tu backend y vuelve a conectar:

ws.onclose = async () => {
  // Conexión perdida o cerrada: solicitar un nuevo token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Mejores prácticas de seguridad

Unas pocas reglas esenciales mantienen seguras tus conexiones:

  • Nunca expongas tu clave de API principal en el cliente
  • Mantén la vida útil (expires_after.seconds) lo más corta posible: si tu sesión media dura cinco minutos, entre 300 y 600 segundos es suficiente
  • Valida las solicitudes de token en el servidor (autenticación de usuario, limitación de tasa)
  • Registra la creación de tokens para detectar usos anómalos
  • Rota tu clave de API principal si sospechas que ha sido comprometida

Puntos clave

  • Una clave de API directa solo es adecuada para aplicaciones de servidor
  • Los tokens efímeros son imprescindibles para aplicaciones del lado del cliente (navegador, móvil)
  • Define la vida útil del token con expires_after.seconds y manténla corta (300 segundos en el ejemplo oficial)
  • El flujo recomendado: tu backend genera el token y tu front-end lo pasa como subprotocolo xai-client-secret. para abrir el WebSocket
  • Planifica siempre la renovación automática de tokens