# Granular Access Control for Cloudflare Workers: A New Era of Secure Team Collaboration
## The Problem with Broad Permissions
As teams increasingly rely on automated agents and CI/CD pipelines to build and deploy applications, the traditional approach to access control has become a liability. When every team member or automated workflow is granted broad, account-wide permissions, the risk of accidental changes in production grows significantly. An agent tasked with debugging a single application could unintentionally modify or delete an entirely different Worker — simply because it had the keys to the kingdom.
Cloudflare recognized this challenge and introduced a fundamentally new approach: resource-level access controls paired with purpose-built roles that let you grant exactly the right amount of access to exactly the right resources.
## Four Roles Built for Real Workflows
The core of this new system is a set of four roles, each designed around a specific level of interaction with a Worker:
**Metadata Read-Only** — Think of this as a “debugging lens.” It allows a person or agent to view settings, metrics, logs, and traces for a specific Worker, but it keeps the source code hidden. This is the perfect role for an observability agent that needs to investigate performance issues or errors without ever seeing the underlying logic. It can query analytics, pull logs, and inspect traces, but the code itself remains protected.
**Content Read-Only** — Sometimes you need a second set of eyes on the code without giving anyone the ability to change it. This role lets a teammate or code review agent read the Worker’s source code and understand how it works, but prevents any modifications, deployments, or settings changes. It’s ideal for pull request reviews, audits, or any scenario where understanding the code matters more than editing it.
**Editor** — This is the workhorse role for active development. An Editor can read and write product content, update settings, and deploy new versions of a Worker. Crucially, it cannot create or delete the resource, which means a misconfigured deployment pipeline or an exposed API token can make changes but cannot take the application offline by deleting it.
**Admin** — The highest level of trust. Admin grants full control over a Worker, including the ability to rename, delete, and manage access for other users. Even at this level, access can be scoped to a single Worker, ensuring that an administrator responsible for one application cannot touch others in the account.
## Scoping Access to the Individual Resource
What makes these roles powerful is the ability to scope them at three distinct levels. At the Developer Platform level, a role applies to all resources across the platform. At the product level, it targets every resource of a specific type — for example, every Worker in an account. At the resource level, access is confined to a single Worker.
This three-tier model means you can start broad and narrow down as needed. For most team workflows, the resource level is where the real security value lies. When you assign a role to a specific Worker, the person or agent receiving that access will only see and interact with that one application in the dashboard.
## Practical Use Cases
**Debugging Without Exposure** — An engineer investigating an issue in production can use the Metadata Read-Only role to pull logs, metrics, and traces through the API. Since the scope is limited to a single Worker, the investigation stays contained. The engineer sees what happened and why, but never gets access to the proprietary code running in that Worker.
**Code Review Without Risk** — A teammate reviewing a proposed change to a Worker’s code can use Content Read-Only to fetch and read the source, submit feedback, and ensure the logic is sound — all without the ability to deploy their own version or alter the settings.
**CI/CD With Containment** — A continuous integration pipeline typically needs to deploy a new version of a Worker after passing tests. By creating an API token with the Editor role scoped to one Worker, the pipeline can push updates safely. If the token is compromised, the damage is bounded: the attacker can deploy changes to that one Worker but cannot delete it or reach any other application.
**Full Management With Boundaries** — For team leads or project owners who need complete control over a specific Worker — including the ability to delete it if needed — the Admin role scoped to that resource provides total management without opening the door to the rest of the account.
## Routes, Custom Domains, and Additional Permissions
Adding a route or Custom Domain to a Worker is a sensitive operation. Because changing a route can redirect live traffic or take an application offline, access to the Worker alone is not sufficient. To manage routes, you need both the Editor role on the Worker and the Workers Routes permission for the connected zone.
This separation is deliberate. It means someone can control how traffic reaches a Worker without gaining the ability to modify unrelated DNS or zone-level settings. The permission model respects the boundary between application logic and network routing.
## Durable Objects and Access Inheritance
Durable Objects do not have their own independent permission system. Instead, access to a Durable Object is inherited from the Worker that implements it. To grant someone access to a Durable Object, you assign them the appropriate role for that Worker.
This means Metadata Read-Only on a Worker also grants access to the Durable Object’s metrics, logs, and traces — but not the data stored inside the object. To read or modify that stored data, the Editor role is required, since Durable Objects Data Studio allows direct interaction with the object’s contents.
## Smarter Error Messages for Permission Issues
When a narrowly scoped token or user tries to perform an operation beyond their permissions, the system now provides more than just a generic access denied response. The APIs return a helpful error that includes a link to the relevant documentation, clearly indicating which specific permissions are needed.
This transforms a frustrating roadblock into a learning opportunity. Whether you’re a developer troubleshooting a deployment or an agent trying to complete a task, the error message tells you exactly what permission to request — no guesswork, no over-provisioning of access.
## Replacing Legacy Permissions
Cloudflare has been running worker-specific permissions for some time using a patchwork of legacy roles like Workers Scripts Read, Workers CI Edit, and Workers Observability Telemetry Edit. The new role system consolidates and replaces all of these with a cleaner, more consistent model.
The migration path is straightforward. Legacy roles and permissions continue to function, and existing assignments will not break. However, Cloudflare recommends transitioning to the new roles since they are the foundation for the upcoming resource-level access controls across all Developer Platform products. There is no set deprecation date for legacy roles, and users will receive advance notice before any changes are made.
## Looking Ahead: A Consistent Platform-Wide Model
Worker-level access controls are just the beginning. Cloudflare has announced plans to bring the same resource-level scoping and these four roles to additional Developer Platform products, including D1 databases, R2 storage buckets, and KV namespaces.
The vision is simple but powerful: instead of granting someone access to every database or every bucket in an account, you will be able to scope access to a specific resource and pair it with the precise role needed. A data analyst might get Metadata Read-Only on a D1 database to inspect query performance, while a developer gets Editor on an R2 bucket to upload and manage files — and neither has access to anything beyond their assigned resource.
This consistent authorization model across the entire Developer Platform represents a significant step forward in how teams secure their cloud applications.
## Frequently Asked Questions
**Can I assign these roles to individual users or to groups?**
Both. You can assign a role to a specific user, or you can create a User Group and assign the policy to the group. Members added to the group will automatically inherit the permissions, which is useful for teams working on the same project.
**How do I create an API token scoped to a specific Worker?**
You can generate an API token through the Cloudflare dashboard or via the API. When creating the token, you specify the role and scope it to a particular Worker. This token can then be given to an agent, a CI/CD system, or any other automated workflow that needs to interact with only that one application.
**Do these roles work for both dashboard and API access?**
Yes. Whether a team member logs into the dashboard or uses the API, the same role-based permissions apply. A user with Metadata Read-Only on a Worker will only see that Worker in the dashboard and can only query metadata through the API.
**What happens if an agent tries to perform an action it doesn’t have permission for?**
The operation will be rejected with a clear error message. For API requests, the response includes a link to the documentation that describes exactly which permissions are required, making it easy to adjust the token’s scope if needed.
**Are the legacy roles being removed?**
No. Legacy roles and permissions continue to work. Cloudflare has not set a deprecation date, and existing assignments will remain functional. The recommendation is to begin migrating to the new roles to take advantage of the improved scoping and the consistent model across all Developer Platform products.
**Will these roles apply to other Cloudflare products beyond Workers?**
Yes. Cloudflare has confirmed that D1, R2, KV, and other Developer Platform products will adopt the same roles and resource-level scoping in the future. The exact rollout timeline may vary by product, but the architecture is designed to be consistent across the entire platform.
## Conclusion
Cloudflare’s introduction of resource-level access controls and four purpose-built roles marks a meaningful shift in how teams and automated agents interact with their applications. By moving away from broad, account-wide permissions and toward granular, scoped access, teams can ship faster with greater confidence. The principle of least privilege is no longer a theoretical best practice — it is a practical, configurable reality.
Whether you are managing a small team of developers or running complex CI/CD pipelines with multiple agents, these controls give you the tools to define exactly who can do what, and to which resources. Combined with smarter error messages and a clear path toward platform-wide consistency, this update positions Cloudflare’s Developer Platform as a more secure and flexible foundation for building on the edge.
Thank you for reading
