Cloudflare Workers 2026: Autorização Granular para Agentes

Em 2026-09-15 a Cloudflare entregou a maior reformulação de controle de acesso da Developer Platform em anos: quatro papéis com escopo por Worker, três níveis de escopo e uma forma de prender qualquer um deles a um único Worker. O post de lançamento é "Give every teammate and agent the right level of access to your Workers", datado de 2026-09-15, e o recurso está no ar para todos os clientes hoje.

A frase importa mais do que parece. Por uma década a API da Cloudflare tratou Workers como um recurso plano da conta: um token com Workers Scripts:Edit podia fazer deploy, renomear ou deletar todos os Workers da conta. Se você rodava um Worker que alimenta um endpoint de arquivo social na Cloudflare, não tinha um jeito limpo de dar a um agente de IA ou token de CI apenas o acesso suficiente para publicar código sem entregar as chaves do resto da conta. Os papéis novos resolvem isso — e foram desenhados, nas palavras da própria Cloudflare, para que "um agente pudesse usar as APIs Cloudflare para investigar um problema sem ver dados de nenhum outro Worker na conta".

Os Quatro Papéis Novos, Em Uma Tabela

A Cloudflare agrupou dezenas de micro-permissões em exatamente quatro papéis, cada um refletindo um nível que você de fato concederia:

Todo papel pode ser definido em um de três escopos. Do mais permissivo ao mais estreito: Account (vale para todos os Workers da conta), Zone (vale para os Workers associados a uma zona) e Individual Worker (vale para um Worker nomeado). A Cloudflare afirmou que os mesmos quatro papéis serão estendidos a D1, R2 e KV, com o mesmo princípio — Metadata Read-Only inspeciona schema D1 ou metadata de bucket R2 sem mostrar linhas ou objetos.

Por Que "Editor com Escopo a Um Worker" É o Padrão Certo Para um Agente

O papel mais útil para um agente de IA é Editor, com escopo em um Worker individual. O próprio exemplo da Cloudflare é o workflow CI/CD que só deve poder publicar o aplicativo que possui: "Se o workflow estiver mal configurado ou o token dele vazar, o impacto permanece contido: ele publica mudanças naquele Worker, mas não pode deletá-lo nem tocar em nenhum outro aplicativo da conta."

Para um Worker de arquivo social que busca posts do X, Bluesky ou LinkedIn e grava no R2, essa é a regra que você realmente quer. No modelo antigo, um token CI vazado podia reescrever o Worker para exfiltrar seu bucket R2, apontá-lo para um namespace KV diferente ou simplesmente deletar o Worker e tirar a API do ar. No modelo novo, Editor com escopo naquele único Worker consegue publicar código que toca aquele único Worker e só aquele Worker.

Note um detalhe sutil mas importante: Editor não pode deletar o próprio Worker. Essa é a propriedade que torna Editor seguro para entregar a um agente. A capacidade de deletar um Worker fica reservada ao Admin. Então mesmo se a injeção de prompt do agente o levar a algo destrutivo, o pior caso é um deploy ruim, não um aplicativo ausente.

Como Criar um Token de API com Escopo no Painel Cloudflare

O post de lançamento percorre a receita. A versão curta, para um Worker de arquivo social chamado social-archive-api:

1. Abra o painel Cloudflare e vá em Meu Perfil → API Tokens → Criar Token.
2. Escolha o template Edit Cloudflare Workers e personalize.
3. Em Recursos da Conta, escolha o Worker ao qual o token deve se aplicar. Defina o escopo como Worker e selecione social-archive-api.
4. Em Permissões, escolha o papel do Worker: Editor para agente ou token CI, Metadata Read-Only para token apenas de debug.
5. Salve o token uma vez e copie. A Cloudflare mostra o valor do token só na criação.

# Um deploy CI para o Worker de arquivo social usando um token Editor com escopo
# O token SÓ consegue publicar este Worker; não pode deletar nem tocar em mais nada.

CLOUDFLARE_API_TOKEN=<seu...token
# O comando de deploy em si não muda.
npx wrangler deploy \
  --name social-archive-api \
  --compatibility-date 2026-09-01

# Se este token vazar, o pior caso é:
#   - alguém consegue enviar código novo para este Worker
#   - NÃO pode deletar o Worker
#   - NÃO pode ler seu código-fonte (Editor escreve; não inclui vazamento de source pela API)
#   - NÃO pode publicar em outro Worker da conta

Como Rotas e Custom Domains Interagem Com o Escopo do Worker

Um ponto em que o modelo novo fica sutil é o roteamento. A rota ou Custom Domain de um Worker é configurada na zona, não no Worker. O bloco de rota de exemplo da Cloudflare em wrangler.jsonc se parece com isto:

{
  "route": {
    "pattern": "example.com/*",
    "zone_name": "example.com"
  }
}

Como mudar uma rota pode redirecionar tráfego de produção ou tirar o Worker do ar, adicionar, remover ou mudar uma rota exige Editor no Worker E permissão Workers Routes para a zona. O raciocínio da Cloudflare: quem administra como o tráfego chega ao Worker não deve também poder mudar configurações não relacionadas do domínio.

Uma vez configurada a rota, deploys que não mudam a rota não exigem mais a permissão da zona. Isso significa que um token CI pode seguir publicando o Worker sem também manter acesso aos seus domínios, bancos ou storage. É a letra miúda que torna Editor com escopo a um Worker genuinamente útil.

Durable Objects Seguem o Papel do Worker

Se seu Worker de arquivo social expõe um Durable Object (por exemplo, um store de sessão por usuário que rastreia quais posts ele já buscou para não re-arquivar duplicados), o Durable Object não tem papel próprio. O acesso é determinado inteiramente pelo papel no Worker que o implementa.

Consequência concreta: Metadata Read-Only no Worker permite que o agente veja métricas, logs e traces do Durable Object — mas não os dados armazenados no objeto. Para consultar ou modificar esses dados, o agente precisa de Editor no Worker. A Cloudflare é explícita que essa separação se manterá quando os mesmos papéis forem levados para D1, R2 e KV: Metadata Read-Only inspeciona schema ou metadata de bucket sem expor linhas ou objetos.

O Que Muda Quando um Token Não Tem o Papel Certo

O lançamento também traz uma melhoria pequena mas de alto impacto nas mensagens de erro da API: em vez de retornar um genérico 403 Forbidden quando um token não tem o papel certo, a API Cloudflare agora inclui um link para a documentação relevante explicando exatamente qual permissão é exigida.

O motivo de isso importar na prática é debug. O modo de falha antigo para um agente que recebeu o token errado era um 403 silencioso e um humano confuso tentando descobrir qual das dezenas de permissões legadas da Cloudflare conceder. No modelo novo, a própria mensagem de erro aponta para o papel que o agente precisa — e dá para promover a partir dali sem conceder acesso mais amplo do que o trabalho exige.

Como o ThreadGrab Usa Isso Na Prática

Os Workers do ThreadGrab que alimentam a API de arquivo social em /functions/api/ se encaixam no mesmo padrão. Um Worker busca posts do X, Bluesky e LinkedIn, grava em um bucket R2 da Cloudflare e serve um endpoint JSON pequeno. O Worker é todo o raio de destruição de qualquer token CI ou agente que o toca. Até 2026-09-15 a única opção segura era tokens com escopo de conta, com o dono humano como único Editor — o que tornava impossível dar a um agente de IA a capacidade de publicar um hotfix.

Com os papéis novos conseguimos separar isso de forma limpa:

• Editor com escopo em social-archive-api — entregue ao agente e ao pipeline CI. Publica, não deleta, não toca outros Workers.
• Metadata Read-Only — entregue a um token separado só de debug usado por dashboards de observabilidade que precisam puxar logs e métricas.
• Admin — mantido só pelo dono humano, usado quando um Worker precisa ser renomeado ou aposentado.

O resultado é o padrão que a Cloudflare explicitamente recomenda — e o padrão que deve ser o default para qualquer Worker que um agente de IA ou token CI toca.

Perguntas Frequentes

A Conclusão

O lançamento da Autorização Granular de Workers de 2026-09-15 não é uma atualização de menu de configurações; é a primeira vez que a Cloudflare entrega um modelo de menor privilégio que cabe em como Workers são realmente usados hoje — por agentes de IA e tokens CI, não por humanos clicando em painéis. Para quem roda um Worker que um agente toca, a migração é a mesma: escolha Editor com escopo no Worker para o agente, segure Admin para você, e aposente o token Scripts:Edit com escopo de conta. A mudança nas mensagens de erro torna o resto de graça.