Olha só o problema que todo mundo já viveu
Sabe quando você precisa dar acesso pra um colega novo, pra pipeline de CI/CD, ou — mais recente — pra um agente de IA que vai mexer na sua infra? A tentação é sempre a mesma: "ah, dá logo um token de Admin e resolve". Só que aí você quebra o princípio do menor privilégio de um jeito brutal. Um token vazado com Workers Scripts Edit significava acesso a TODOS os Workers da sua conta. Inclusive o que tá servindo produção. 😱
A Cloudflare acabou de lançar controle de acesso por Worker com quatro roles novas, permitindo escopar tudo até um recurso específico. É o primeiro passo pra um modelo de autorização consistente em toda a Developer Platform (D1, R2 e KV vêm aí).
Vamos ver o que mudou na prática e como migrar sem quebrar sua pipeline. Vamos lá! 🚀
As quatro roles novas
Ao invés daquele blob genérico de "Workers Admin", agora você escolhe uma role (o que pode fazer) e um escopo (em quais recursos).
| Role | O que permite | Quando usar |
|---|---|---|
| Metadata Read-Only | Ver listas, settings, métricas, logs e traces. Sem acesso ao conteúdo. | Agente de debug ou plantonista que precisa de observabilidade, mas não do código. |
| Content Read-Only | Ler código do Worker / conteúdo do D1. Sem escrita. | Bots de code review, auditoria de segurança, dev novo no time. |
| Editor | Ler + escrever conteúdo e atualizar settings. Não cria nem deleta. | Tokens de CI/CD, agentes que fazem deploy. |
| Admin | Controle total, incluindo deletar e conceder acesso. | Dono de um Worker específico, apenas. |
Escopos: três níveis
Cada role pode ser aplicada em um destes níveis:
- Developer Platform — todos os recursos da plataforma.
- Produto — todos os recursos de um produto (ex: todos os Workers).
- Recurso — um Worker específico, um DB D1, um bucket.
Criando um token escopado a um Worker
No dashboard, ao criar o token, você seleciona o Worker como escopo. O wrangler.toml continua igual — quem limita o estrago é o token, não o arquivo:
# wrangler.toml
name = "meu-worker"
main = "src/index.ts"
compatibility_date = "2024-09-23"
# Rota é permissão separada — precisa de
# Workers Routes na zona pra mexer aqui.
[[routes]]
pattern = "exemplo.com.br/*"
zone_name = "exemplo.com.br"
# Cria um token escopado a UM Worker com role Editor
# (dashboard: Manage Account > Members > API Tokens)
export CLOUDFLARE_API_TOKEN="<token-escopado>"
# Esse deploy só mexe no meu-worker, mesmo se o token vazar.
npx wrangler deploy
Durable Objects herdam do Worker
Durable Objects não têm roles próprias. O acesso vem do Worker que os implementa. Pra debugar um DO, dá Metadata Read-Only no Worker. Pra consultar ou alterar estado via Data Studio, precisa de Editor.
Mapa de migração: roles antigas → novas
A Cloudflare não vai deprecar as roles antigas (por enquanto), mas vale migrar já — só as novas suportam escopo em nível de recurso.
| Role antiga | Role nova recomendada |
|---|---|
| Workers Platform (Read-Only) | Developer Platform Content Read-Only |
| Workers Platform Admin | Developer Platform Admin |
| Workers Scripts Read | Content Read-Only |
| Workers Scripts Edit | Editor |
| Workers CI Read | Content Read-Only |
| Workers CI Edit | Editor |
| Workers Observability Read | Metadata Read-Only |
| Workers Observability Edit | Editor |
| Workers Observability Telemetry Edit | Editor |
| Workers Tail Read | Metadata Read-Only |
Limitações e pegadinhas 🧐
- Rotas e Custom Domains são permissão separada. Editar rota exige Editor no Worker + Workers Routes na zona. Isso é intencional — você não quer um token de CI redirecionando tráfego de produção silenciosamente.
- Deploy que não mexe em rota é seguro. Uma vez configurada a rota, o CI pode subir novas versões sem acesso à zona.
- Dados de Durable Object ficam atrás de Editor. Metadata Read-Only não te deixa inspecionar estado pelo Data Studio.
- Sem data de deprecação das roles antigas. Atribuições existentes continuam funcionando, mas você perde o benefício do escopo.
- Erros 403 melhores. Agora as APIs linkam pra doc exata de permissão — útil quando seu agente precisa se autodiagnosticar.
Próximos passos
- Audite seus tokens de API. Todo token com
Workers Scripts Edité candidato a virar Editor + escopo em Worker. - Crie User Groups pra times com o mesmo padrão de acesso, em vez de atribuir pessoa por pessoa.
- Re-tokenize seu CI/CD. Cada pipeline ganha seu próprio Editor escopado ao Worker que ele faz deploy.
- Escope seus agentes. Se o agente só precisa debugar, dá Metadata Read-Only — não Editor.
- Fique de olho no rollout de D1 / R2 / KV. As mesmas quatro roles vão valer; já padronize sua nomenclatura.
Referência completa na documentação de autorização do Cloudflare Workers.
A real sacada
O interessante dessa release não são as quatro roles — tabela de RBAC é chata. É que a Cloudflare está tratando agentes de IA como identidades de primeira classe, que merecem tokens próprios e escopados. É uma mudança silenciosa, mas importante: o modelo de ameaça agora inclui atores não-humanos que chamam suas APIs sozinhos.
Se você já roda agentes contra infra, isso é obrigatório no seu stack. Se ainda não, comece escopando os tokens do CI — a disciplina é a mesma.
Leia também
- Beyond Demos: Building Production-Ready AI Agents with Gemini 3 & 6 Open-Source Frameworks — como colocar agentes em produção de verdade, não só em demo.
- From Monolith to Millisecond Latency: The Event-Driven Blueprint Behind Amazon Key — por que least-privilege e arquitetura event-driven andam juntos em escala.