Build1 publisher2 min readPublished
Scoping an agent to one Worker filters what Cloudflare's API returns to it
Cloudflare has shipped four Workers roles at three scopes to all customers, so an agent's API token can now carry one of them for a single application. Resource-level control for D1, R2 and KV is still a plan.
The Engineer · Build desk
What happened
- Cloudflare has added four Workers roles, available today to all customers, that can be assigned to a person or written into an API token scoped to a single Worker and handed to an agent.
- One level allows debugging a resource without exposing its content, the next reading content without changing it, the third making changes without being able to delete, and the fourth full management.
- Each role attaches at one of three scopes: every Developer Platform resource, every resource of one product such as all Workers, or one specific resource such as a single Worker.
- Cloudflare says it plans to use the same four roles as it brings resource-level access controls to other Developer Platform products, including D1, R2 and KV.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- exposure A CI token that leaks now bounds what an attacker gets: with Editor scoped to one Worker it can deploy to that Worker, and it cannot delete it or reach another application in the account.
- decision Reading a Worker's code and deploying it become separate grants, so whoever runs a review agent has to decide which one it gets instead of inheriting both.
- cost Scoping by resource means a token per workflow per Worker, so issuance and rotation now scale with the number of applications a team deploys.
The grant shows up in two places. In the dashboard, a user with a scoped role sees only the Worker they were given [5]. At the API, Cloudflare wrote that a scoped caller's observability requests "only return data for the Workers they have access to" [6]. The API behaviour is the half an agent touches, since an agent does not log into a dashboard. According to the post, an agent scoped to one Worker can use the Cloudflare APIs to investigate an issue without seeing data from any other Worker in the account [7].
Two axes set a grant. The role picks one of four levels [3]. The scope picks the whole Developer Platform, one product, or one named resource [4]. Four levels at three scopes gives twelve combinations for a single resource [15], small enough to write down in a runbook and argue about at review. Cloudflare wrote that it was aiming between two failure modes: "Overly broad roles force you to grant more access than intended, undermining the principle of least privilege, while providing too many individual permissions makes it difficult to know which ones to grant" [10].
For the least-privilege claim to transfer to your agent, that agent's whole job has to be expressible as operations on Workers. If it also has to read one KV key or one R2 object, the resource scope has nothing to attach to yet, because Cloudflare describes resource-level controls for D1, R2 and KV as work it plans to do [11]. The storage half of the credential then has to be granted at the product or platform scope [4].
Of the roles the post walks through, Metadata Read-Only is the one I would hand a debugging agent: settings, metrics, logs, traces, GraphQL analytics, and no source code [8]. Cloudflare says it plans to hold that line for storage too, so a holder could inspect settings and observability data for a D1 database or an R2 bucket without reading the values in the database or the files in the bucket [12]. The reason the post gives for the whole exercise is short. Cloudflare wrote that "the last thing you want is for an agent to make a change in production, just because it was granted more access than it needs" [14].
What to watch
- Whether resource-level roles actually ship for D1, R2 and KV, and whether Content Read-Only there means reading rows and objects.
- Whether scoped tokens can be minted programmatically per workflow, since hand-issuing one token per Worker does not scale.