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

Proteja a Sua Chave de API: Nunca a Exponha no Lado do Cliente

Aula 6 de 12 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. Uma Chave de API é uma Palavra-passe
  2. Vetores Comuns de Exposição
  3. Arquitetura de Proxy: A Solução
  4. Armazenamento Seguro de Chaves
  5. O Que Fazer se a Sua Chave For Comprometida
  6. Pontos-chave

Uma Chave de API é uma Palavra-passe

A sua chave de API da xAI funciona como uma palavra-passe com acesso total à sua conta. Quem a tiver pode efetuar chamadas à API às suas custas, aceder aos seus modelos e, potencialmente, comprometer os seus dados. Em que difere de uma palavra-passe padrão? Uma chave roubada pode ser utilizada silenciosamente: não verá nada até chegar a fatura ou até a sua equipa financeira emitir um alerta. A regra é simples e absoluta: nunca exponha uma chave de API no lado do cliente.

Vetores Comuns de Exposição

O caso mais comum é a inclusão direta da chave no JavaScript do frontend:

// PERIGO - NUNCA faça isto
const response = await fetch("https://api.x.ai/v1/chat/completions", {
  headers: { "Authorization": "Bearer xai-abc123..." }
});

Uma vez implementado, este código fica visível para qualquer pessoa que utilize as ferramentas de desenvolvimento do navegador. Basta abrir o separador «Network» para ler a chave em texto simples nos cabeçalhos do pedido.

Um vetor mais insidioso, porque cria uma falsa sensação de segurança: as variáveis de ambiente do frontend. Variáveis com o prefixo NEXT_PUBLIC_, VITE_ ou REACT_APP_ são incorporadas no JavaScript no momento da compilação e, portanto, tornam-se públicas. O programador pensa que «manteve a chave fora do código»; na realidade, ela foi simplesmente compilada nele:

# PERIGO - esta variável estará no pacote final
NEXT_PUBLIC_XAI_API_KEY=xai-abc123...

Os repositórios Git são o terceiro vetor clássico. Mesmo um commit eliminado permanece no histórico do Git: se tiver cometido o erro de incluir uma chave, reescrever o histórico não é suficiente, porque clones e forks podem tê-la retido. Considere-a comprometida e revogue-a imediatamente. Por fim, as chaves também vazam por vias indiretas, mais difíceis de imaginar, mas muito comuns: registos de aplicação que rastreiam cabeçalhos completos, mensagens de erro exibidas ao utilizador ou ferramentas de monitorização que capturam pedidos de saída.

Arquitetura de Proxy: A Solução

A única abordagem segura é intermediar todas as chamadas através do seu backend:

Cliente (navegador/móvel)
    ↓ pedido sem chave de API
O Seu Backend (servidor)
    ↓ adiciona a chave de API (variável de ambiente)
API da xAI
    ↓ resposta
O Seu Backend
    ↓ reencaminha a resposta (filtrada se necessário)
Cliente

Eis um proxy minimalista em Python:

# Backend Python (Flask)
import os
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
XAI_KEY = os.environ["XAI_API_KEY"]  # Variável apenas no lado do servidor

@app.route("/api/chat", methods=["POST"])
def proxy_chat():
    user_message = request.json.get("message")

    response = requests.post(
        "https://api.x.ai/v1/chat/completions",
        headers={"Authorization": f"Bearer {XAI_KEY}"},
        json={
            "model": "grok-4.3",
            "messages": [{"role": "user", "content": user_message}]
        }
    )

    return jsonify(response.json())

Para além de proteger a chave — que nunca é transmitida ao cliente —, o proxy oferece-lhe um ponto de controlo impossível de alcançar com chamadas diretas. Pode filtrar pedidos: limitação de taxa para impedir que um cliente esgote a sua quota, validação de entrada e moderação de conteúdos. Controla quais os modelos acessíveis, impedindo que um cliente comprometido invoque um modelo dispendioso e gere custos inesperados. Pode registar as chamadas para auditoria — uma necessidade central para um responsável pela conformidade. E pode colocar em cache certas respostas para reduzir custos em pedidos repetitivos.

Armazenamento Seguro de Chaves

No lado do servidor, a base é a variável de ambiente, carregada a partir de um ficheiro .env que nunca deve ser submetido para o Git:

# Ficheiro .env (NUNCA submetido para o Git)
XAI_API_KEY=xai-your-secret-key

Adicione sistematicamente estes ficheiros ao seu .gitignore:

# .gitignore
.env
.env.local
.env.production

Para ambientes de produção, um ficheiro .env colocado num servidor continua a ser um processo manual frágil: prefira um gestor de segredos dedicado. Opções comprovadas incluem o AWS Secrets Manager ou o SSM Parameter Store, o Google Secret Manager, o Azure Key Vault, o HashiCorp Vault, ou o Doppler e o Infisical para estruturas mais ligeiras. O que estas ferramentas oferecem em relação a um ficheiro simples: rotação automática de chaves, auditoria de acessos — quem leu qual segredo e quando — e encriptação em repouso. Estes são elementos que pode apresentar tal e qual durante uma auditoria de segurança, ao passo que um ficheiro de texto numa máquina não prova nada.

O Que Fazer se a Sua Chave For Comprometida

Se suspeitar que uma chave foi exposta, a ordem das operações é tão importante quanto as próprias operações. Revogue a chave na consola da xAI (console.x.ai) antes de qualquer outra coisa: cada minuto em que a chave comprometida permanece ativa é um minuto de possível exploração, e a continuidade do serviço trata-se depois, não antes. Em seguida, gere uma nova chave e atualize os seus backends para restabelecer o serviço.

O incidente ainda não está encerrado. Audite a utilização procurando chamadas de API suspeitas no seu histórico de faturação — um pico num período de tempo invulgar, utilização atribuída a um modelo que não utiliza. Identifique a origem da fuga; caso contrário, a nova chave seguirá o mesmo caminho que a antiga. Termine por analisar o seu código com ferramentas como gitleaks ou truffleHog, que também percorrem o histórico do Git e revelam frequentemente outros segredos esquecidos há muito tempo.

Pontos-chave

  • Uma chave de API é uma palavra-passe com acesso total à sua conta
  • Sempre intermedie as chamadas à API através do seu backend
  • As variáveis NEXT_PUBLIC_, VITE_, REACT_APP_ são públicas
  • Utilize um gestor de segredos em produção
  • Se uma chave for comprometida, revogue-a imediatamente e audite a utilização