Tokens efímeros y seguridad
En esta página
Actualizado el 3 de noviembre de 2026, basado en la referencia de la API de Voz de xAI. Fuentes: Tokens efímeros · Referencia de la API de Voz · Reanudación de sesión.
El problema de tener una clave de API en el cliente
Una aplicación de voz que se ejecuta en un navegador o en un teléfono no puede incluir tu clave de API. Cualquier visitante puede abrir las herramientas de desarrollo, leer la clave desde el paquete de JavaScript o desde una cabecera de la solicitud y utilizarla en tu cuenta hasta que se agote tu cuota. Ninguna cantidad de ofuscación protege un valor que el cliente debe poseer para llamar a la API.
La respuesta de xAI son los tokens efímeros, también llamados secretos de cliente: un token de corta duración, generado por tu servidor, que autoriza una sesión de voz y nada más.
Cómo funciona
El flujo se reduce a cinco pasos:
- Tu backend (un servidor seguro) llama a
POST /v1/realtime/client_secretscon tu clave de API. - La API devuelve un token temporal con una duración limitada.
- Tu backend envía ese token al cliente (navegador o aplicación móvil).
- El cliente utiliza el token para conectarse al WebSocket del Agente de Voz.
- El token caduca tras la duración que hayas elegido (
expires_after.seconds).
Lo que pueda filtrarse en el lado del cliente ahora tiene mucho menos valor: un token que caduca en minutos y solo puede abrir una sesión de voz, no tu clave de API. En el servidor, generar uno requiere unas pocas líneas de código. Observa que el manejador comienza comprobando al usuario: sin esa comprobación, tu backend sería simplemente un dispensador público de tokens.
// Backend en Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
// Comprueba que el usuario esté autenticado
if (!req.user) return res.status(401).json({ error: "No autorizado" });
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 } // 10 minutos, el valor predeterminado
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
El cliente solo conoce tu propia ruta: solicita un token y luego abre el WebSocket con él.
// Frontend (navegador)
async function startVoiceSession() {
// Solicita un token al backend
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// El WebSocket del navegador no acepta cabeceras:
// el token va en un subprotocolo, con el prefijo "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... configuración de la sesión
}
La arquitectura de extremo a extremo
En conjunto, el flujo comienza con el usuario iniciando sesión en tu aplicación. Su cliente solicita entonces un token de voz a tu backend, y el backend verifica la autenticación y los permisos antes de generar el token efímero a través de la API de xAI. El token regresa al cliente, que lo utiliza para abrir la sesión del Agente de Voz, y caduca automáticamente al final de su vida útil.
Esa comprobación entre la solicitud y la generación convierte un simple relevo en un punto de control, y ahí es donde residen tus reglas de negocio. Puedes limitar el número de sesiones de voz por usuario y día, de modo que una sola cuenta no pueda consumir todo tu presupuesto mensual durante la noche. Puedes reservar tokens para suscripciones activas, aplicando tu modelo de negocio en un lugar distinto a la interfaz. Puedes limitar la frecuencia de las solicitudes para evitar que un cliente defectuoso o malintencionado pida mil tokens por minuto. Y puedes registrar cada token que generes: es tu única base fiable para la monitorización, la facturación interna y el análisis de incidentes.
Reglas que nunca debes romper
La clave de API nunca llega al cliente, bajo ninguna forma. Manténla fuera del JavaScript del front-end y fuera de cualquier variable de entorno expuesta a la compilación del navegador (las variables con prefijo para inyectarse en el paquete acaban siendo públicas). Manténla también fuera de las URL, los registros y los mensajes de error mostrados a los usuarios.
A continuación, mantén la duración tan corta como sea práctico. Según la referencia de la API, expires_after.seconds tiene un valor predeterminado de 600 segundos y un máximo de 3.600; la documentación utiliza 300 en sus ejemplos. Sobre todo, el token debe ser válido cuando el cliente abre la conexión. Una duración corta reduce la ventana de tiempo durante la cual un token interceptado puede ser utilizado.
La documentación no indica si un token que caduca corta una conexión que ya está abierta. Si tu cliente necesita reconectarse, tras una caída de red o durante una sesión muy larga, solicita un nuevo token y utiliza la reanudación de sesión: habilita resumption.enabled en session.update, conserva el ID que recibes en conversation.created y vuelve a abrir el WebSocket con ?conversation_id=<id>. Los turnos anteriores se repiten y el modelo retoma donde lo dejó.
async function reconnect(conversationId) {
const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
ws.onopen = () => ws.send(JSON.stringify({
type: "session.update",
session: { resumption: { enabled: true } }, // enviar de nuevo en cada conexión
}));
return ws;
}
Para TTS en modo HTTP, existe una alternativa aún más sencilla a los tokens: un proxy. El cliente envía su texto a tu backend, y tu backend llama a TTS y devuelve el audio. La clave nunca sale de tu servidor y obtienes un lugar natural para filtrar contenido y medir el uso en el proceso.
Puntos clave
- Los tokens efímeros aseguran el acceso al Agente de Voz desde aplicaciones del lado del cliente.
POST /v1/realtime/client_secretsdevuelvevalueyexpires_at;expires_after.secondstiene un valor predeterminado de 600 y un máximo de 3.600.- En el navegador, el token va en el subprotocolo
xai-client-secret.<token>. - Tu backend debe comprobar la autenticación y los permisos antes de generar un token.
- Nunca expongas tu clave de API en el cliente, en URLs ni en registros.
- Para TTS HTTP, el uso de un proxy a través de tu backend es una alternativa válida a los tokens efímeros.