Cloudflare Workers Granular Permissions: A Massive Security Upgrade (And How to Migrate Now)
Jack BeamanShare
On September 15, 2026, Cloudflare announced granular Worker-level permissions, a fundamental rework of how access to Cloudflare Workers is controlled. If you deploy serverless applications on Cloudflare's platform, this is not a minor feature update. It is the single most important security improvement to Workers access control since the platform launched.
Here's what changed, and exactly how to migrate your team and pipelines off the legacy model.
The Problem: Account-Wide Blast Radius
Before this update, Cloudflare Workers permissions operated at the account or product level. There was no way to scope access to a single Worker. A CI/CD token that only needed to deploy one application could also modify or delete every other Worker in the account. A debugging agent that needed to read logs could also read source code for every Worker you run.
The legacy roles looked like this:
| Legacy Role | Type | Recommended New Role |
|---|---|---|
| Workers Platform (Read-Only) | Member | Content Read-Only |
| Workers Platform Admin | Member | Admin |
| Workers Scripts Read | API Token | Content Read-Only |
| Workers Scripts Edit | API Token | Editor |
| Workers CI Read | API Token | Content Read-Only |
| Workers CI Edit | API Token | Editor |
| Workers Observability Read | API Token | Metadata Read-Only |
| Workers Observability Edit | API Token | Editor |
| Workers Observability Telemetry Edit | API Token | Editor |
| Workers Tail Read | API Token | Metadata Read-Only |
Source: Cloudflare Blog
Every one of these roles granted access to all Workers in the account. A single compromised token meant an attacker could take down your entire serverless deployment, not just one application.
What Changed: Four Roles, Three Scopes
The new model introduces four Worker-level roles, each available at three scope levels:
The Four Roles
| Role | Permissions |
|---|---|
| Metadata Read-Only | View settings, metrics, logs, and traces without access to Worker code or the ability to make changes. |
| Content Read-Only | Read Worker code, settings, and observability data without the ability to modify or deploy changes. |
| Editor | Update and deploy a Worker without the ability to delete it. |
| Admin | Everything in Editor, plus the ability to delete the Worker. |
Source: Cloudflare Changelog
The Three Scope Levels
- Developer Platform level — access to metadata for all Developer Platform resources
- Product level — access to every resource of one product type (e.g., all Workers)
- Resource level — access to one specific Worker
This means you can now hand a CI/CD pipeline an Editor token scoped to a single Worker. If that token leaks, the attacker can deploy changes to that one Worker but cannot delete it, cannot touch any other Worker, and cannot access databases, domains, or storage across the account.
A Massive Security Upgrade
1. Blast Radius Containment
Under the legacy model, a compromised CI/CD token could delete any Worker in your account. Under the new model, a scoped Editor token can deploy to one Worker and cannot delete it. The blast radius of a single compromised credential drops from your entire Workers estate to a single application.
2. Source Code Isolation
A debugging agent with Metadata Read-Only can query analytics, logs, and traces through the GraphQL API without ever seeing Worker source code. This was impossible before, observability access and code access were bundled together.
3. Code Review Agents Without Deploy Risk
Content Read-Only lets an AI code review agent read and analyze Worker code without any ability to modify or deploy. You can now safely integrate AI into your review pipeline without handing it write access.
4. Dashboard Visibility Filtering
A user assigned access to a specific Worker will see only that Worker when logging into the Cloudflare dashboard. No information disclosure about other applications in the account.
5. API Response Filtering
API requests from a scoped token return data only for Workers the agent has access to. Previously, a broad token could accidentally expose data from other applications through API responses.
6. Route and Domain Isolation
Changing a Worker route could previously redirect production traffic or take an application offline with broad zone access. The new model requires a separate Workers Routes permission for the zone, so someone managing Worker traffic cannot change unrelated domain settings.
7. Better Developer Experience on Errors
Previously, unauthorized API calls returned a generic 403 Forbidden with no guidance. Now they include a link to documentation showing the exact permissions required, reducing debugging time and frustration.
The Biggest Win: Safe AI Agent Integration
As development teams integrate AI agents into their workflows (debugging, code review, deployment) the old model forced an unacceptable choice: give the agent broad account-level access (dangerous) or do not use agents at all (limiting).
The new scoped API tokens let you hand an agent a token restricted to a single Worker with exactly the role it needs:
- Debugging agent — Metadata Read-Only: inspect settings, metrics, logs, and traces without seeing source code
- Code review agent — Content Read-Only: read and analyze code without deploy or modification rights
- Deployment agent — Editor: deploy updates without deletion capability or access to other Workers
- Full control agent — Admin: complete control over one Worker, scoped so it cannot touch anything else
This follows zero-trust principles for non-human identities — a critical capability as AI-assisted development becomes standard practice.
How to Migrate from Legacy Permissions
Cloudflare has not set a deprecation date for legacy roles, they continue to work. But the security risk of staying on account-wide permissions exists today. Here is the migration path.
Step 1: Audit Your Current Permissions
Inventory every member, User Group, and API token with Workers access. Map each to its new equivalent using the legacy role table above. Pay special attention to:
- CI/CD tokens using Workers Scripts Edit or Workers CI Edit — these should become Editor scoped to specific Workers
- Observability tokens using Workers Observability Read or Workers Tail Read — these should become Metadata Read-Only
- Any token using Workers Scripts Read or Workers CI Read — these should become Content Read-Only
Step 2: Create Scoped Permission Policies for Team Members
- Go to Manage Account then Members in the Cloudflare dashboard
- Select the member
- Create a permission policy
- Set the scope to Individual Workers
- Select the specific Workers the member needs access to
- Choose the appropriate role
For teams, create a User Group, assign the policy to the group, and add members — they inherit the policy automatically.
Step 3: Create Scoped API Tokens for CI/CD and Agents
- Go to Manage Account then Account API Tokens
- Create a new account-owned API token
- Set the scope to Specified Workers
- Select only the Worker or Workers the token needs
- Choose the role, typically Editor for CI/CD deployment, Content Read-Only for code review agents, Metadata Read-Only for debugging or observability agents
Step 4: Handle Routes and Custom Domains
If the Worker uses routes or Custom Domains, grant Editor access to the Worker and also grant Workers Routes permission for the zone. Once routes are configured, CI/CD can continue deploying new Worker versions without zone-level access, as long as the deployment does not change the route configuration.
Step 5: Handle Durable Objects
Durable Objects inherit permissions from their parent Worker, they do not have their own roles. Grant the appropriate role for the Worker that implements the Durable Object:
- Metadata Read-Only — access to Durable Object metrics, logs, and traces, but not stored data
- Editor — required to access or modify stored data through Durable Objects Data Studio
Step 6: Update Terraform Configurations
If you manage permissions as code, update your Terraform resources to use the new role names and scope definitions. The new granular permissions are fully supported through Terraform.
Step 7: Rotate Old Tokens and Remove Legacy Roles
Once new scoped tokens are in place and verified working:
- Update CI/CD pipelines and agent configurations to use the new tokens
- Revoke the old account-wide API tokens
- Remove legacy role assignments from members
- Verify that all workflows still function correctly
You Should Do This Immediately
No deprecation deadline exists yet, but the security risk exists today. Every day a legacy CI/CD token with account-wide Workers Scripts Edit remains in use is a day where:
- A leaked token from your CI/CD system can delete any Worker in your account
- A compromised debugging agent can read source code for every application you deploy
- A misconfigured pipeline can take down production applications it was never meant to touch
The blast radius of a single compromised token under the legacy model is your entire Workers deployment. Under the new model, it is a single Worker, and even then, the Editor role prevents deletion.
NIST Cybersecurity Framework 2.0 Alignment
For organizations aligning with NIST CSF 2.0, this migration directly supports:
- PR.AA-05 — least-privilege access control
- PR.AA-03 — separation of duties
- ID.AM-01 — inventorying and managing physical and software assets (scoped tokens make this tractable)
The Bottom Line
The migration is low-risk. Legacy roles continue to work, there is no cutover deadline, and you can create new scoped policies alongside existing ones before removing anything. The security improvement is immediate the moment you swap a broad token for a scoped one.
Cloudflare has made this available to all customers at no additional cost. There is no reason to wait.
Key sources: