The Problem With "Just Give It Admin"
If you've ever onboarded a teammate, wired up a CI/CD pipeline, or (more recently) handed an AI agent a Cloudflare API token, you've felt the tension: broad tokens are convenient, but they violate the principle of least privilege in the worst way. A single leaked CI token with Workers Scripts Edit used to mean someone could touch every Worker in your account — including the one serving production traffic.
Cloudflare just shipped Worker-level access controls with four new roles that let you scope access down to a single resource. This is the first step toward a consistent authorization model across the whole Developer Platform (D1, R2, KV coming next).
Here's what actually changed and how to use it without breaking your existing pipelines.
The Four New Roles
Instead of a flat "Workers Admin" blob, you now pick a role and a scope. The role answers what someone can do; the scope answers which resources.
| Role | What it allows | When to use it |
|---|---|---|
| Metadata Read-Only | View resource lists, settings, metrics, logs, traces. No product content. | Debugging agent or on-call engineer who needs observability but not source. |
| Content Read-Only | Read Worker code / D1 content. No writes. | Code review bots, security auditors, new hires. |
| Editor | Read + write content, update settings. Cannot create or delete. | CI/CD deploy tokens, agents that ship changes. |
| Admin | Full control, including delete and grant access. | Owner of a specific Worker only. |
Scopes: Three Levels
Each role can be attached at one of three scopes:
- Developer Platform level — every resource across the platform.
- Product level — every resource of one product (e.g. all Workers).
- Resource level — one specific Worker, D1 DB, or bucket.
Creating a Worker-scoped API token
When you create an API token in the Cloudflare dashboard, you now select the Worker as the scope. Here's the shape of a Wrangler config that still works once the token is scoped — note that the token itself is what limits blast radius, not this file:
# wrangler.toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-09-23"
# Routing is separate from Worker access — you need
# Workers Routes permission on the zone to change this.
[[routes]]
pattern = "example.com/*"
zone_name = "example.com"
# Create a token scoped to ONE Worker with Editor role
# (via dashboard: Manage Account > Members > API Tokens)
export CLOUDFLARE_API_TOKEN="<scoped-token>"
# This deploy only touches my-worker, even if the token leaks.
npx wrangler deploy
Durable Objects follow the Worker
Durable Objects don't have their own roles. Access is inherited from the Worker that implements them. To let someone debug a DO, give them Metadata Read-Only on the Worker. To let them query or mutate DO state via Data Studio, they need Editor.
Legacy Roles → New Roles Migration Map
Cloudflare isn't deprecating the old roles (yet), but you should migrate now because only the new roles support resource-level scoping.
| Legacy Role | Recommended New Role |
|---|---|
| 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 |
Limitations and Gotchas
- Routes and Custom Domains are a separate permission. Editing a Worker's route requires Editor on the Worker + Workers Routes on the zone. This is deliberate — you don't want a CI token to silently redirect production traffic.
- Deploys that don't touch routes are safe. Once a route is configured, CI can ship new versions without any zone access, as long as the connection isn't changed.
- Durable Object data is behind Editor. Metadata Read-Only won't let you inspect stored state via Data Studio — that's a write-capable surface.
- No deprecation date for legacy roles yet. Existing assignments keep working, but you're leaving scoping benefits on the table.
- Better 403s. API errors now link to the exact permission docs instead of a dead-end "Forbidden". Useful when your agent needs to self-diagnose.
Next Steps
- Audit your existing API tokens. Any token with
Workers Scripts Editis a candidate for Editor + Worker scope. - Create User Groups for teams that share the same access pattern instead of assigning per-person.
- Re-token your CI/CD. Each pipeline gets its own Editor token scoped to the one Worker it deploys.
- Scope your agents. If an AI agent only needs to debug, give it Metadata Read-Only — not Editor.
- Watch for D1 / R2 / KV rollout. The same four roles will apply; plan your naming conventions now.
For the full reference, see the Cloudflare Workers authorization docs.
The Real Takeaway
The interesting part of this release isn't the four roles — RBAC tables are boring. It's that Cloudflare is treating AI agents as first-class identities that deserve their own scoped tokens. That's a quiet but important shift: the threat model now includes a non-human actor that can autonomously call your APIs.
If you're already running agents against infrastructure, this should be table stakes in your stack. If you're not, start by scoping your CI tokens — the same discipline applies.
Related Reading
- Beyond Demos: Building Production-Ready AI Agents with Gemini 3 & 6 Open-Source Frameworks — how to actually ship agents, not just demo them.
- From Monolith to Millisecond Latency: The Event-Driven Blueprint Behind Amazon Key — why least-privilege and event-driven design go hand in hand at scale.