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

Autenticação com token Bearer

Aula 14 de 14 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Proteja as suas chamadas à API
  2. O esquema Bearer token
  3. Erros de autenticação
  4. Melhores práticas de segurança
  5. Deteção de fugas
  6. HTTPS obrigatório
  7. Pontos-chave
  8. Verifique a sua compreensão

Proteja as suas chamadas à API

Guia de introdução na documentação da xAI Todas as requisições enviadas à API da xAI devem ser autenticadas. A API utiliza o esquema Bearer token, um padrão amplamente adotado para APIs REST. Esta lição explica como funciona este mecanismo e as melhores práticas para proteger as suas chaves em produção.

O esquema Bearer token

Como o nome sugere, quem possui (“carrega”) o token pode aceder à API. É por isso que proteger a sua chave é fundamental: não existe verificação de identidade além do próprio token.

Formato do cabeçalho

Cada requisição HTTP deve incluir o cabeçalho Authorization com o prefixo Bearer seguido da sua chave:

Authorization: Bearer xai-your-api-key

Com cURL, fica assim:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}'

Em Python, os SDKs tratam deste cabeçalho automaticamente quando passa a chave ao construtor do cliente.

Erros de autenticação

HTTP 401 Unauthorized

Este erro significa que a sua chave está em falta, é inválida ou foi revogada. Verifique:

  • Se a variável de ambiente XAI_API_KEY está definida
  • Se a chave começa por xai-
  • Se a chave não foi revogada na consola

HTTP 403 Forbidden

A sua chave é válida, mas não tem as permissões necessárias para a ação solicitada. Isto pode acontecer devido a restrições de equipa em certas operações.

Melhores práticas de segurança

Nunca exponha uma chave no código

As chaves nunca devem aparecer em texto simples em:

  • Código fonte versionado (Git)
  • Logs da aplicação
  • URLs ou parâmetros de consulta
  • Mensagens de erro mostradas aos utilizadores
  • Issues e pull requests no GitHub

Utilize um cofre de segredos

Em produção, guarde as suas chaves num sistema dedicado:

  • AWS Secrets Manager ou Parameter Store
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Segredos da sua plataforma de CI/CD (GitHub Actions, GitLab CI)

Rotação de chaves

Altere as suas chaves regularmente e imediatamente se suspeitar de uma fuga:

  1. Crie uma nova chave na consola da xAI
  2. Atualize a chave no seu cofre de segredos
  3. Volte a implementar a sua aplicação
  4. Verifique se tudo funciona com a nova chave
  5. Revogue a chave antiga na consola

Limite as permissões

Se trabalhar em equipa, crie chaves separadas para cada serviço e ambiente. Se uma for comprometida, o impacto permanece limitado a um único contexto.

Deteção de fugas

O prefixo xai- permite que ferramentas de deteção (GitHub secret scanning, GitGuardian, TruffleHog) identifiquem chaves no código fonte automaticamente. Ative estas ferramentas nos seus repositórios para ser alertado imediatamente em caso de exposição acidental.

Se uma chave for detetada num commit público:

  1. Revogue-a imediatamente na consola da xAI
  2. Verifique o seu histórico de utilização para identificar uso fraudulento
  3. Crie uma nova chave
  4. Limpe o seu histórico Git (ou, melhor ainda, considere a chave como comprometida e avance)

HTTPS obrigatório

A API da xAI apenas aceita ligações HTTPS. O TLS encripta as suas requisições em trânsito, incluindo o cabeçalho Authorization. Nunca tente contornar esta proteção: uma requisição via HTTP não encriptado exporia a sua chave na rede.

Pontos-chave

  • A API utiliza o esquema Bearer token através do cabeçalho Authorization
  • A chave é o único fator de autenticação: proteja-a como uma palavra-passe
  • Utilize um cofre de segredos em produção e nunca codifique uma chave diretamente no código
  • Ative a deteção de fugas nos seus repositórios Git
  • Rode as chaves regularmente e revogue imediatamente qualquer chave comprometida

Verifique a sua compreensão

Os fundamentos da API da xAI: uma última verificação antes de começar a construir.

1. O que deve fazer com uma chave de API assim que a criar?

Resposta: Guarde-a num local seguro (é mostrada apenas uma vez), exponha-a através da variável XAI_API_KEY em vez de a codificar diretamente, utilize uma chave por ambiente e teste-a imediatamente com uma chamada a /v1/models.

2. Qual é o URL base e porque é tão importante?

Resposta: https://api.x.ai/v1. É o que torna possível a compatibilidade com a OpenAI: alterar o base_url e a chave é suficiente para direcionar código existente da OpenAI para o Grok.

3. Quais os SDKs que pode utilizar com o Grok?

Resposta: O SDK nativo da xAI, o SDK da OpenAI (com o base_url da xAI) e o Vercel AI SDK no lado JavaScript, além do cURL para testes: o ecossistema é aberto.

4. Qual é o principal endpoint de geração?

Resposta: POST /v1/responses, o formato moderno; chat/completions permanece disponível como uma opção legada para compatibilidade.

5. Como é autenticada cada requisição?

Resposta: Com o cabeçalho Authorization: Bearer e a chave xai-…: o esquema standard Bearer token, o mesmo independentemente do SDK ou ferramenta.

Uma chave segura, o URL base, a sua escolha de SDK, Bearer em toda a parte: a base está lançada e os próximos cursos de API constroem sobre ela.