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

ACLs e o Princípio do Privilégio Mínimo

Aula 8 de 12 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. O Princípio do Privilégio Mínimo Aplicado a APIs
  2. O Sistema de ACL da xAI
  3. Limites de Taxa: Uma Camada de Segurança Adicional
  4. Uma Estratégia de Chave por Ambiente
  5. Verificar e Auditar Permissões
  6. Pontos-chave

O Princípio do Privilégio Mínimo Aplicado a APIs

O princípio do privilégio mínimo é um dos conceitos mais antigos na cibersegurança: cada componente de um sistema deve ter acesso apenas aos recursos estritamente necessários para o seu funcionamento. A ideia é intuitiva quando a transpomos para o mundo físico — não entrega a chave mestra do edifício à pessoa que rega as plantas do átrio. Aplicado às chaves de API da xAI, isto significa que cada chave deve estar limitada apenas aos endpoints e modelos que a aplicação que a utiliza realmente necessita. Se esta chave alguma vez for comprometida, o atacante herdará as suas permissões: uma chave restrita ao chat com um único modelo causa infinitamente menos danos do que uma chave que abre todo o catálogo.

A xAI implementa este princípio através de um sistema granular de ACL (Access Control List), que detalharemos abaixo.

O Sistema de ACL da xAI

As ACLs seguem o formato api-key:{type}:{value}. Dois tipos dizem-lhe respeito no dia a dia: api-key:endpoint:{endpoint} restringe os endpoints acessíveis e api-key:model:{model_id} restringe os modelos utilizáveis. Existe também um carácter universal, api-key:endpoint:*, que concede acesso a todos os endpoints — conveniente para desenvolvimento, proibido em produção, precisamente porque anula o benefício do privilégio mínimo.

Os endpoints que pode autorizar individualmente são: chat (conclusão de chat, de longe o mais comum), embed (geração de embeddings), image (geração e edição de imagens), models (consulta da lista de modelos), tokenize (tokenização de texto), documents (gestão de documentos) e sample (amostragem).

Vejamos como isto se traduz num exemplo real. Imagine um chatbot de apoio ao cliente que utiliza apenas o modelo grok-4.3 em modo de chat. A sua chave ideal seria assim:

{
  "name": "support-chatbot-prod",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.3"
  ],
  "qps": 5,
  "qpm": 100,
  "tpm": 500000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Leia esta configuração como um contrato: a chave só pode aceder ao endpoint de chat — sem imagens, sem embeddings, logo sem possível utilização indevida para esses fins. Só pode utilizar o grok-4.3, o que impede chamadas acidentais (ou maliciosas) a modelos mais dispendiosos. Está limitada a 5 pedidos por segundo e 100 por minuto, e expirará numa data conhecida. Se algum programador do projeto tentar adicionar geração de imagens sem avisar ninguém, a API recusará: a restrição técnica faz cumprir a decisão arquitetural.

Limites de Taxa: Uma Camada de Segurança Adicional

As ACLs respondem à pergunta «o quê», os limites de taxa respondem a «quanto». O QPS (Queries Per Second) limita os pedidos por segundo: esta é a sua salvaguarda contra picos acidentais — o ciclo infinito introduzido por uma refatorização numa sexta-feira à noite, ou um ataque DDoS que rebate na sua aplicação. O QPM (Queries Per Minute) suaviza o tráfego num período mais longo e deteta abusos que passariam despercebidos ao radar do QPS. O TPM (Tokens Per Minute), finalmente, limita o volume de tokens consumidos: protege contra pedidos individuais muito longos — um utilizador que cola um documento de 200 páginas no seu chatbot — que esgotariam o seu orçamento em minutos sem nunca exceder o número autorizado de pedidos.

Uma Estratégia de Chave por Ambiente

Na prática, não configura uma única chave, mas sim uma família de chaves, e cada ambiente tem a sua própria lógica. No desenvolvimento, inverte a lógica de produção: acesso amplo, limites apertados.

{
  "name": "dev-team-alpha",
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 2,
  "qpm": 30,
  "tpm": 100000,
  "expireTime": "2026-06-30T23:59:59Z"
}

Os programadores podem explorar tudo, mas os limites baixos evitam surpresas na faturação se um teste correr mal. No staging, pelo contrário, replica exatamente as ACLs de produção (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): esta é a única forma de detetar um problema de permissões a montante — se o código de staging tentar efetuar uma chamada que a produção recusará, é melhor descobri-lo agora do que na primeira hora de entrada em produção. A chave de produção, no entanto, combina as permissões estritas do staging com limites dimensionados para o tráfego real (por exemplo, QPS 20, QPM 600, TPM 2000000) e uma expiração agendada — "expireTime": "2027-03-31T23:59:59Z" numa chave chamada prod-chatbot-v2.

Verificar e Auditar Permissões

Para ver o que uma chave ativa tem realmente permissão para fazer, consulte a API com a própria chave:

curl https://api.x.ai/v1/api-key \
  -H "Authorization: Bearer $XAI_API_KEY"

A resposta lista as ACLs efetivas, os estados api_key_blocked e api_key_disabled, uma versão mascarada da chave (redacted_api_key) e o team_id. Adote o hábito de comparar regularmente estas ACLs com as necessidades reais da aplicação: as permissões tendem a acumular-se ao longo do tempo, nunca diminuindo espontaneamente. Do lado dos modelos, o endpoint GET /auth/teams/{teamId}/models devolve a lista de modelos disponíveis para a sua equipa com os respetivos preços — informação valiosa para definir ACLs de modelos relevantes e excluir modelos dispendiosos que não utiliza.

Para consolidar tudo isto, realize uma auditoria completa às suas chaves. Liste as chaves ativas para cada equipa e, em seguida, consulte cada uma: as suas ACLs são mínimas, sem caracteres universais em produção? Os seus limites de taxa são razoáveis? A data de expiração está definida? O seu nome identifica a aplicação e o ambiente — «prod-chatbot-v2» conta uma história, «key-test-2» não conta nenhuma? Elimine chaves órfãs e documente o resultado: este documento servirá de ponto de partida para a próxima auditoria e permitirá ver num instante o que se desviou entretanto.

Pontos-chave

  • Cada chave deve ter ACLs restritivas: apenas os endpoints e modelos necessários
  • Nunca utilize o carácter universal * em produção
  • Combine ACLs com limites de taxa (QPS, QPM, TPM) adaptados ao uso real
  • Crie chaves distintas por ambiente (dev, staging, prod) e por aplicação — staging com as mesmas ACLs que a produção
  • Audite regularmente as permissões das suas chaves ativas através de GET /v1/api-key