Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Tokens Efêmeros para Ligações WebSocket

Aula 5 de 12 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. O problema: autenticar um cliente sem expor a sua chave
  2. Como funcionam os tokens efêmeros
  3. Escolher a duração adequada
  4. Implementação no backend
  5. Pontos-chave

O problema: autenticar um cliente sem expor a sua chave

Ao desenvolver uma aplicação de voz ou em tempo real com a API Grok, precisa de estabelecer uma ligação WebSocket diretamente a partir do navegador ou do cliente móvel. Encaminhar o tráfego através do seu servidor adiciona latência, o que quebra a fluidez da conversação por voz. No entanto, as ligações diretas criam um problema de autenticação: nunca deve incluir a sua chave de API no código do lado do cliente.

A razão é simples: qualquer chave incorporada em JavaScript de frontend, numa aplicação móvel descompilável ou num binário distribuído fica comprometida no momento da publicação. Qualquer utilizador pode abrir as ferramentas de desenvolvimento do navegador e lê-la. Para resolver isto, a xAI oferece tokens efêmeros: tokens temporários que os clientes podem utilizar sem jamais verem a chave mestra.

600s
Duração predefinida
3600s
Duração máxima
POST
/v1/realtime/client_secrets
Bearer
Token temporário

Como funcionam os tokens efêmeros

A arquitetura segue um princípio: a chave de API nunca sai do seu servidor e o cliente recebe apenas um token de curta duração. O fluxo é curto. O cliente solicita um token ao seu backend, que efetua a chamada POST /v1/realtime/client_secrets com a sua chave de API. Esta chamada é o único local onde a chave aparece, ocorrendo inteiramente no lado do servidor. A xAI devolve um token efêmero com a sua data de expiração, que o seu backend transmite ao cliente. O cliente abre então a ligação WebSocket para wss://api.x.ai/v1/realtime apresentando este token. Em nenhum momento o navegador vê a chave mestra; lida apenas com um token que expira automaticamente.

A chamada de criação a partir do seu backend é assim:

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": 600}}'

E a resposta:

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

Relativamente à duração, existem três referências: não há um limite mínimo documentado (são possíveis alguns segundos), o valor predefinido é de 600 segundos (10 minutos) e o máximo é de 3600 segundos (1 hora).

Escolher a duração adequada

A duração do token deve corresponder ao seu caso de uso, sendo esta escolha uma verdadeira decisão de segurança. Para interações de voz esporádicas — perguntas e respostas, comandos de voz, ditado — uma janela de 300 a 600 segundos é suficiente: a sessão terminará bem antes da expiração. Para conversas de voz sustentadas, como apoio ao cliente, entrevistas ou reuniões assistidas, aponte para 600 a 1800 segundos para evitar cortes a meio da conversação. Sessões de trabalho prolongadas — transcrição em tempo real, monitorização contínua de voz — podem justificar 1800 a 3600 segundos, mas utilize a duração máxima com cautela: esta alarga a janela de exploração caso o token seja roubado.

A regra de ouro resume-se a isto: escolha sempre a menor duração compatível com o seu caso de uso. Se um token for intercetado, uma expiração de dez minutos transforma um incidente potencialmente grave num pequeno incómodo.

Implementação no backend

Eis um exemplo de um proxy seguro em Node.js:

// Rota do backend - NÃO expor no lado do cliente
app.post("/api/realtime-token", authenticateUser, 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 }
      })
    }
  );

  const token = await response.json();
  res.json({ token: token.value, expires_at: token.expires_at });
});

Três detalhes neste exemplo sustentam toda a segurança da configuração. A chave de API reside numa variável de ambiente do servidor, nunca no código. O middleware authenticateUser verifica a identidade do utilizador antes de emitir um token — sem ele, qualquer pessoa poderia obter tokens e consumir a sua quota à sua custa. E apenas o token efêmero, nunca a chave, é devolvido ao cliente.

Algumas armadilhas surgem regularmente nas revisões de código. A chave de API infiltrada no frontend “apenas para o protótipo” acaba invariavelmente em produção. O token criado sistematicamente com a duração máxima, por conveniência, quando o caso de uso exige um quarto desse tempo. O endpoint de geração deixado sem verificação de autenticação, aberto a todos. E a falta de tratamento de renovação no lado do cliente, o que produz erros de expiração a meio da sessão em vez de uma reconexão transparente: uma vez que a resposta fornece expires_at, o seu cliente tem tudo o que precisa para solicitar um novo token antes do prazo, e não depois.

Pontos-chave

  • Os tokens efêmeros permitem a autenticação WebSocket sem expor a sua chave de API
  • Endpoint: POST /v1/realtime/client_secrets (chamada apenas no lado do servidor)
  • Duração configurável desde alguns segundos até um máximo de 3600 segundos (predefinição: 600s)
  • O seu backend atua como um proxy de autenticação entre o cliente e a xAI
  • Escolha sempre a duração mais curta compatível com a sua utilização