Autenticación y tokens efímeros
En esta página
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.secondsy 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