Autenticação e tokens efémeros
Nesta página
Duas formas de autenticar
A API do Agente de Voz oferece duas formas de autenticar a sua ligação WebSocket. A escolha depende de onde o seu código é executado: no servidor ou no cliente.
Chave de API direta (lado do servidor)
O método mais simples consiste em passar a sua chave de API no cabeçalho de autorização ao abrir o WebSocket. Isto funciona para aplicações de servidor, onde a chave permanece protegida:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Nunca utilize este método em código que seja executado no navegador: a chave de API ficaria exposta no código-fonte ou nas ferramentas de desenvolvimento.
Tokens efémeros (lado do cliente)
Para aplicações de front-end (navegador, telemóvel), a xAI fornece tokens efémeros. O seu backend gera um token de curta duração, que depois passa ao cliente para abrir a ligação WebSocket.
Cria um token com um pedido 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}}'
O campo expires_after.seconds define a validade do token, em segundos. O exemplo da documentação oficial utiliza 300 segundos (5 minutos): um token efémero destina-se a cobrir uma sessão de voz, não a durar indefinidamente. Aponte para o tempo de vida mais curto possível que funcione para as suas sessões.
Arquitetura recomendada com tokens efémeros
Eis o fluxo completo para uma aplicação web:
// 1. Lado do servidor (Node.js/Express): gerar o 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 o corpo da resposta da xAI tal como está;
// contém o token efémero
res.json(await response.json());
});
// 2. Lado do cliente (navegador): utilizar o token
// O construtor WebSocket do navegador não aceita cabeçalhos:
// o token vai num SUBPROTOCOL, com o prefixo "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("Voice session started");
};
}
Renovação de tokens
A documentação não especifica se um token que expira fecha uma ligação já estabelecida. De qualquer forma, a sua aplicação precisa de um plano para quando a ligação cair: monitore o evento de fecho, peça um novo token ao seu backend e reconecte:
ws.onclose = async () => {
// Ligação perdida ou fechada: solicitar um novo token
const newToken = await fetchNewToken();
reconnect(newToken);
};
Melhores práticas de segurança
Algumas regras essenciais mantêm as suas ligações seguras:
- Nunca exponha a sua chave de API principal no cliente
- Mantenha o tempo de vida (
expires_after.seconds) o mais curto possível: se a sua sessão média durar cinco minutos, 300 a 600 segundos são suficientes - Valide os pedidos de token no servidor (autenticação do utilizador, limitação de taxa)
- Registe a criação de tokens para detetar utilizações anómalas
- Rode a sua chave de API principal se suspeitar que foi comprometida
Pontos-chave
- Uma chave de API direta só é adequada para aplicações de servidor
- Tokens efémeros são obrigatórios para aplicações do lado do cliente (navegador, telemóvel)
- Defina a duração do token com
expires_after.secondse mantenha-a curta (300 segundos no exemplo oficial) - O fluxo recomendado: o seu backend gera o token e o seu front-end passa-o como subprotocolo
xai-client-secret.para abrir o WebSocket - Planeie sempre a renovação automática de tokens