Chaves de API com o mínimo de permissão

Na parte anterior eu contei como passei a medir as visitas do site sem usar cookies e como resolvi o bloqueio da política de segurança que barrou o nosso próprio contador. Com os números de acesso chegando ao painel da Cloudflare, surgiu a necessidade de levar essas informações até o Analista, o agente que prepara o meu resumo diário.

O que eu queria resolver

Em 3 de outubro de 2026 o meu site pessoal entrou no ar em rodrigoesporto.com. Com o contador funcionando, eu não queria entrar no painel da hospedagem toda manhã apenas para verificar quantas pessoas leram os artigos. Quem cuida disso no meu time de agentes é o Analista: ele acompanha o perfil no X e as visitas do site e manda um resumo curto por dia.

Para fazer esse trabalho sozinho, o Analista precisa consultar os dados da Cloudflare pela internet. Só que existe um jeito perigoso e um jeito seguro de dar essa autorização a um robô.

O jeito perigoso é entregar uma chave geral da conta ou a senha de administrador. Se eu fizesse isso, o agente teria poder para alterar configurações de rede, mexer nos servidores de nomes (DNS), excluir páginas do ar ou até mudar os dados de cobrança do domínio. Pior ainda: se essa credencial vazasse em algum momento, quem colocasse as mãos nela assumiria o controle total do endereço.

Eu precisava do caminho seguro. Queria criar uma permissão cirúrgica: uma credencial feita exclusivamente para leitura de dados estatísticos daquele domínio específico. O Analista precisava conseguir ler os números de tráfego, mas sem nenhuma capacidade de editar arquivos, mexer no DNS ou mudar qualquer vírgula no site.

Trabalho durante o dia e, à noite e aos domingos, construo com agentes de IA. Fui ao painel da Cloudflare para configurar essa autorização restrita.

Como uso a Cloudflare para hospedar as páginas e registrar o domínio, relato aqui as escolhas reais que fiz para o meu próprio caso, sem patrocínio nem neutralidade de manual.

Resumo rápido

• O que funcionou: criei uma chave de API na Cloudflare com permissão exclusiva de leitura de estatísticas para o Analista, e uma segunda chave separada para o Clef a partir de um modelo pronto da plataforma.
• Custo: US$ 0 (recurso disponível no plano gratuito da Cloudflare).
• Tempo: cerca de 30 minutos para criar as chaves, corrigir um erro de cópia e validar a leitura.
• O tropeço: na primeira tentativa, copiei o comando de teste inteiro da tela (que começava com “curl”) em vez de pegar só o código da chave na caixa de cima.
• A regra de ouro: uma chave por uso, sempre com o mínimo de permissão, e nunca colar credenciais na janela de conversa.

Primeiro: o que é uma API e o que é uma chave de API

API vem do inglês Application Programming Interface, ou Interface de Programação de Aplicações. Em termos práticos, é um balcão de atendimento feito para programas de computador conversarem entre si.

Quando você acessa um site, abre um navegador, clica em botões e lê textos na tela. Um robô ou agente de IA não precisa de botões coloridos nem de mouse. Ele conversa com a Cloudflare enviando um pedido de texto pela rede e recebe de volta apenas os dados brutos, como uma tabela enxuta com o número de visitas daquele dia. Esse canal direto de troca de dados é a API.

Uma chave de API funciona como um crachá de identificação para esse balcão. Em vez de o agente digitar login e senha humana toda vez que pede um dado, ele apresenta esse código para provar que tem autorização legítima para consultar o sistema.

Pense no crachá magnético de um prédio comercial. Você passa na recepção, recebe o cartão e encosta na catraca para subir.

A analogia do crachá ajuda a entender a identificação, mas tem um limite claro. No mundo físico, o segurança do saguão olha para o seu rosto e confere se o cartão é seu. No mundo digital, o servidor só enxerga o código enviado pela rede. Qualquer programa que estiver com a chave consegue se passar pelo agente. Por isso, a chave nunca pode ser compartilhada abertamente e deve carregar o menor poder possível.

O que é o princípio do mínimo de permissão

O princípio do mínimo de permissão, também chamado de princípio do menor privilégio, é uma regra simples de segurança: dê a cada programa apenas a autorização indispensável para realizar a tarefa dele, sem nenhum poder extra.

Imagine que você contratou um leitor de hidrômetro para anotar o consumo de água da sua casa uma vez por mês. Você não entrega a ele a chave mestra que abre o portão, a porta da sala, os quartos e o cofre. Você dá apenas a chave da caixinha do relógio de água na calçada. Ele anota o número, fecha a tampa e vai embora.

Com os agentes de IA a lógica é a mesma. O Analista precisa apenas ler números agregados de visitas. Ele não precisa salvar novas versões das páginas, não precisa alterar registros de e-mail e não precisa mexer na segurança do domínio.

A grande vantagem dessa abordagem é o controle de danos. Se uma chave com acesso total vazar, um invasor pode apagar o seu site em poucos segundos. Já se uma chave com o mínimo de permissão vazar, o estrago fica rigorosamente limitado ao que ela pode fazer: o invasor no máximo consulta quantos acessos o site teve naquela semana, mas não consegue alterar nada nem derrubar o endereço.

O que eu usei

• Painel de tokens de API da Cloudflare (Cloudflare API Tokens), no plano gratuito.
• O Analista: acompanha o perfil no X e as visitas do site e manda um resumo curto por dia.
• O Clef: agente do time que recebeu uma segunda chave a partir de um modelo pronto da Cloudflare.
• O Darth: bot principal do time, que recebe qualquer pedido e encaminha para o agente certo.

Não precisei contratar serviços adicionais nem pagar taxas para criar credenciais restritas.

Como foi

Para configurar essa autorização no painel da Cloudflare sem expor a conta, segui este passo a passo:

1. Acessei as configurações do meu perfil de usuário na Cloudflare e entrei na seção de tokens de API.
2. Escolhi a opção de criar um token personalizado para definir as regras manualmente.
3. Configurei a permissão específica da credencial: selecionei apenas a permissão de leitura para a área de estatísticas e métricas de zona (Zone, Analytics, Read).
4. Restringi o escopo da chave: em vez de autorizar todas as zonas da conta, limitei o acesso exclusivamente ao domínio rodrigoesporto.com.
5. Concluí a criação e visualizei o código secreto gerado na tela. A plataforma só mostra esse código uma única vez, então é preciso copiar e guardar no local certo na mesma hora.
6. Guardei o código no campo de configuração protegido do agente, sem colocar o texto no chat comum de conversa.
7. Pedi ao Analista para realizar uma consulta de teste aos dados do site. A consulta retornou os números do contador de primeira, confirmando que a comunicação estava aberta e segura.

Depois de fechar a chave do Analista, criei também uma segunda chave para o Clef. Dessa vez aproveitei um modelo pronto oferecido pela própria Cloudflare, que já traz um conjunto prévio de permissões adequadas para a função dele, mantendo as duas credenciais separadas.

O que deu errado e como resolvi

Nem tudo correu perfeitamente no primeiro clique, e o erro que cometi traz um ensinamento útil para quem está começando.

Quando a Cloudflare conclui a criação de uma chave de API, ela apresenta uma tela de confirmação com dois blocos de texto diferentes. No bloco de cima fica apenas o código alfanumérico da chave, que é a credencial real. No bloco de baixo a tela mostra um exemplo prático de linha de comando para testar no terminal, que começa com a palavra “curl” e inclui o endereço da API junto com a chave embutida.

Na pressa de testar o Analista, cometi um erro primário de atenção: selecionei o bloco de baixo inteiro, copiei a linha de comando com o “curl” e tudo o que vinha junto, e colei aquilo como se fosse a chave do agente.

Quando o agente tentou fazer a primeira chamada usando a frase inteira em vez do código puro, a autenticação falhou imediatamente. Bastou voltar à tela do painel com calma para perceber o engano: o comando de teste era apenas um modelo de exemplo, enquanto a senha real era só o código da caixa de cima. Copiei apenas o código correto, atualizei a credencial e o teste funcionou de imediato.

Desse erro tirei duas lições práticas que viraram regra no time:

Primeira lição: uma chave por uso. Nunca use a mesma chave de API para dois agentes ou duas ferramentas diferentes. Se vários programas compartilham a mesma credencial, surge uma dependência desnecessária. Quando um agente for desativado ou precisar de ajustes, você é obrigado a revogar a chave de todo mundo. Com chaves separadas, você desativa ou altera uma delas sem tocar no restante do time.

Segunda lição: chave nunca vai na conversa. Nunca cole senhas, chaves de API ou segredos técnicos na janela de bate-papo com um agente. As conversas de chat ficam salvas no histórico, podem aparecer na tela do computador e muitas vezes sincronizam em outros aparelhos. Chave de acesso deve ser guardada apenas nas telas de configuração seguras ou nas variáveis de ambiente do sistema, onde ninguém tem acesso visual direto.

Nenhuma dessas ferramentas substitui julgamento. Elas encurtam o caminho entre ’eu sei o que quero’ e ’está no ar'.

Custos e limites

Em dinheiro, essa etapa custou zero. A Cloudflare permite criar tokens de API personalizados sem cobrança no plano gratuito.

Em tempo, levei cerca de 30 minutos para criar as duas chaves, descobrir o erro da cópia do comando de teste e validar a leitura dos dados pelo Analista.

Os limites dessa solução são as próprias barreiras de proteção que escolhi erguer:

• A chave do Analista só lê estatísticas de tráfego. Se o agente tentar fazer qualquer outra ação, como consultar registros de servidores ou alterar uma regra de segurança, a Cloudflare bloqueia a requisição na hora com um erro de permissão.
• Se o domínio mudar ou se eu criar um novo site no futuro, essa chave não funcionará para o novo endereço, pois foi amarrada especificamente a rodrigoesporto.com.
• A chave tem validade enquanto eu mantiver o token ativo no painel. Posso revogar ou excluir a credencial com um clique a qualquer momento se notar qualquer comportamento estranho.

O que eu faria diferente

Eu teria olhado com mais calma para os blocos da tela final da Cloudflare antes de sair copiando o conteúdo.

Perdi alguns minutos achando que a permissão estava errada quando o problema era apenas ter colado um comando de exemplo no lugar do código da chave. Prestar atenção no formato do que a plataforma entrega economiza tempo e evita dúvidas falsas sobre a configuração.

Para quem serve e para quem não serve

Serve para quem usa agentes de IA, scripts ou programas automáticos para consultar serviços externos e quer manter seus dados e seu site protegidos contra erros ou vazamentos.

Serve também para quem busca aprender boas práticas de segurança digital desde o primeiro projeto, entendendo que permissão em excesso é sempre um risco desnecessário.

Não serve para quem tem pressa e prefere usar a chave mestre da conta por comodidade, ignorando os riscos de entregar acesso irrestrito para uma rotina automática.

Não serve para tarefas que realmente precisem de controle total sobre a infraestrutura, situações em que permissões mais amplas são necessárias e exigem um cuidado ainda mais rigoroso com o armazenamento das credenciais.

Fechamento

Construir com IA vai além de gerar textos ou imagens; envolve cuidar da infraestrutura básica que mantém tudo seguro nos bastidores. Limitar as chaves de API ao mínimo necessário dá a tranquilidade de saber que cada agente cumpre o seu papel sem colocar a conta em risco.

Se você está conectando assistentes ou rotinas automáticas a serviços na nuvem, acostume-se a restringir cada permissão desde o primeiro dia. Para acompanhar os próximos passos desta jornada e conversar sobre essas experiências, estou no X: @RodrigoesPorto.

Na próxima parte eu conto como a Arte criou os avatares animados do time, trazendo uma cara própria para cada agente com os capacetes da família do Darth.

Fontes e links

• Documentação oficial da Cloudflare sobre tokens de API: https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
• Registro interno de lições aprendidas da equipe, 3 de outubro de 2026.