Tokens efémeros e segurança
Nesta página
Atualizado a 3 de novembro de 2026, com base na referência da API de Voz da xAI. Fontes: Tokens Efémeros · Referência da API de Voz · Retoma de Sessão.
O problema de ter uma chave de API no cliente
Uma aplicação de voz executada num navegador ou num telemóvel não pode incluir a sua chave de API. Qualquer visitante pode abrir as ferramentas de programador, ler a chave no pacote JavaScript ou num cabeçalho de pedido e, em seguida, utilizá-la na sua conta até esgotar a sua quota. Nenhuma quantidade de ofuscação protege um valor que o cliente precisa de ter para chamar a API.
A resposta da xAI são os tokens efémeros, também chamados segredos de cliente: um token de curta duração, gerado pelo seu servidor, que autoriza uma sessão de voz e nada mais.
Como funciona
O fluxo resume-se a cinco passos:
- O seu backend (um servidor seguro) chama
POST /v1/realtime/client_secretscom a sua chave de API - A API devolve um token temporário com uma duração limitada
- O seu backend envia esse token para o cliente (navegador ou aplicação móvel)
- O cliente utiliza o token para ligar ao WebSocket do Agente de Voz
- O token expira após a duração que escolheu (
expires_after.seconds)
O que pode vazar no lado do cliente passa a ter muito menos valor: um token que expira em minutos e só pode abrir uma sessão de voz, não a sua chave de API. No servidor, gerar um requer apenas algumas linhas de código. Note que o handler começa por verificar o utilizador: sem essa verificação, o seu backend é apenas um distribuidor público de tokens.
// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
// Verificar se o utilizador está autenticado
if (!req.user) return res.status(401).json({ error: "Unauthorized" });
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, o padrão
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
O cliente só conhece a sua própria rota: pede um token e, em seguida, abre o WebSocket com ele.
// Frontend (navegador)
async function startVoiceSession() {
// Pedir um token ao backend
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// O WebSocket do navegador não aceita cabeçalhos:
// o token vai num subprotocolo, prefixado com "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... configuração da sessão
}
A arquitetura de ponta a ponta
No conjunto, o fluxo começa com o utilizador a iniciar sessão na sua aplicação. O cliente pede então um token de voz ao seu backend, e o backend verifica a autenticação e as permissões antes de gerar o token efémero através da API da xAI. O token regressa ao cliente, que o utiliza para abrir a sessão do Agente de Voz, expirando automaticamente no fim da sua duração.
Essa verificação entre o pedido e a geração transforma um simples retransmissor num ponto de controlo, e é aí que residem as suas regras de negócio. Pode limitar o número de sessões de voz por utilizador por dia, para que uma única conta não consuma todo o seu orçamento mensal durante a noite. Pode reservar tokens para subscrições ativas, aplicando o seu modelo de negócio noutro local que não a interface. Pode limitar a taxa de pedidos, para que um cliente com erros ou malicioso não possa pedir mil tokens por minuto. E pode registar cada token que gera: é a sua única base fiável para monitorização, faturação interna e análise de incidentes.
Regras que nunca deve quebrar
A chave de API nunca vai para o cliente, sob nenhuma forma. Mantenha-a fora do JavaScript de front-end e fora de qualquer variável de ambiente exposta à compilação do navegador (variáveis prefixadas para serem injetadas no pacote tornam-se públicas). Mantenha-a também fora de URLs, registos e mensagens de erro mostradas aos utilizadores.
Em seguida, mantenha a duração o mais curta possível. De acordo com a referência da API, expires_after.seconds tem o padrão de 600 segundos e um máximo de 3.600; a documentação utiliza 300 nos seus exemplos. Acima de tudo, o token precisa de ser válido quando o cliente abre a ligação. Uma duração curta reduz a janela durante a qual um token intercetado pode ser utilizado.
A documentação não indica se um token que expira corta uma ligação que já está aberta. Se o seu cliente precisar de se religar, após uma queda de rede ou durante uma sessão muito longa, peça um novo token e utilize a retoma de sessão: ative resumption.enabled em session.update, guarde o ID que recebe em conversation.created e, em seguida, reabra o WebSocket com ?conversation_id=<id>. As trocas anteriores são repetidas e o modelo retoma onde parou.
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 novamente em cada ligação
}));
return ws;
}
Para TTS no modo HTTP, existe uma alternativa ainda mais simples aos tokens: um proxy. O cliente envia o seu texto para o seu backend, e o seu backend chama o TTS e devolve o áudio. A chave nunca sai do seu servidor e obtém um local natural para filtrar conteúdo e medir a utilização no processo.
Pontos-chave
- Os tokens efémeros garantem o acesso ao Agente de Voz a partir de aplicações do lado do cliente
POST /v1/realtime/client_secretsdevolvevalueeexpires_at;expires_after.secondstem o padrão de 600 e um máximo de 3.600- No navegador, o token vai no subprotocolo
xai-client-secret.<token> - O seu backend deve verificar a autenticação e as permissões antes de gerar um token
- Nunca exponha a sua chave de API no cliente, em URLs ou em registos
- Para TTS HTTP, o uso de um proxy através do seu backend é uma alternativa válida aos tokens efémeros