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

Autenticação e tokens efémeros

Aula 2 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Duas formas de autenticar
  2. Arquitetura recomendada com tokens efémeros
  3. Melhores práticas de segurança
  4. Pontos-chave

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.seconds e 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