[Workers, R2] Add permissions access docs#31672
Conversation
github-actions
Bot
assigned
GregBrimble,
irvinebroque,
korinne,
MattieTK,
vy-ton and
WalshyDev
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review summary
This PR adds three new pages under /workers/authorization/ that document Developer Platform permissions, Workers role scopes, and R2 access options. This is a solid first subset for authorization docs.
What changes:
- Overview (
index.mdx): Explains the three-level scope model (platform, product, resource) and the four role tiers. - Workers (
workers.mdx): Details Workers-specific roles, scopes, Wrangler permission requirements, legacy permission mappings, Pages API token roles, bindings, and limitations. - R2 (
r2.mdx): Covers R2 member roles, R2 API tokens, and account API token permission groups for storage, data catalog, and SQL.
Issues flagged:
- Broken link to a non-existent Durable Objects permissions page.
- Trailing slashes after URL anchors in three places on the Workers page.
- Descriptions on the R2 and Workers pages are shorter than the style guide recommends (50–160 characters).
- R2 page title could be more descriptive for consistency.
Please address the broken link and description lengths before merging. The trailing-slash and title items are quick fixes.
| @@ -0,0 +1,128 @@ | |||
| --- | |||
| title: Workers permissions and access | |||
| description: Manage roles and scopes for Workers. | |||
There was a problem hiding this comment.
The description is 37 characters. The style guide recommends 50–160 characters for SEO and clarity. Consider expanding this to explain what actions the page covers (e.g., viewing, deploying, and managing Workers roles and scopes).
| | ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Tail logs for a Worker | `wrangler tail` | `Metadata Read-Only` for that Worker | | ||
| | Deploy an existing Worker | `wrangler deploy` | `Editor` for that Worker | | ||
| | Deploy an existing Worker with routes | `wrangler deploy` | `Editor` for that Worker, plus [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains/) for each zone referenced by routes | |
There was a problem hiding this comment.
Remove the trailing slash after the anchor fragment. The correct format is /fundamentals/manage-members/scope/#specific-domains (trailing slash on the path, not after the fragment).
| | Workers Observability Edit | `Editor` | | ||
| | Workers Observability Telemetry Edit | `Editor` | | ||
| | Workers Routes Read | `Metadata Read-Only` | | ||
| | Workers Routes Edit | `Editor`, plus [zone-level permission](/fundamentals/manage-members/scope/#specific-domains/) for each zone referenced by routes | |
There was a problem hiding this comment.
Remove the trailing slash after the anchor fragment: /fundamentals/manage-members/scope/#specific-domains.
| - Product-level Workers roles do not grant access to other Developer Platform products such as [R2](/r2/), [D1](/d1/), [KV](/kv/), [Queues](/queues/), [Vectorize](/vectorize/), or [Hyperdrive](/hyperdrive/). | ||
| - API tokens do not support platform-level Developer Platform permissions. | ||
| - Creating a new Worker requires Workers Admin because per-Worker permissions can only apply to Workers that already exist. | ||
| - Deploying a Worker with routes also requires [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains/) for each zone referenced by those routes. |
There was a problem hiding this comment.
Remove the trailing slash after the anchor fragment: /fundamentals/manage-members/scope/#specific-domains.
| ## Related resources | ||
|
|
||
| - [Permissions and access overview](/workers/authorization/) | ||
| - [Durable Objects permissions and access](/workers/authorization/durable-objects/) |
There was a problem hiding this comment.
This links to /workers/authorization/durable-objects/, which does not exist yet. Since this PR is described as the "first subset" and follow-ups will add additional pages, this link will be broken. Consider removing this bullet or replacing it with plain text (e.g., "Durable Objects permissions and access — coming soon") until the page is added.
| @@ -0,0 +1,74 @@ | |||
| --- | |||
| title: R2 | |||
There was a problem hiding this comment.
Consider a more descriptive title for consistency with the Workers page, such as R2 permissions and access.
| @@ -0,0 +1,74 @@ | |||
| --- | |||
| title: R2 | |||
| description: Review R2 access options. | |||
There was a problem hiding this comment.
The description is only 26 characters. The style guide recommends 50–160 characters. Consider expanding to describe what access models and token types the page covers.
|
I've completed the review of PR #31672. Labels applied
What the PR changesThis PR introduces three new pages under
Issues flagged
Review postedA review with inline comments has been posted to PR #31672:
|
|
/bonk can you make updates to address feedback? |
Co-authored-by: dinasaur404 <dinasaur404@users.noreply.github.com>
|
Done! I've addressed all the feedback from the review on PR #31672. Here's what was changed:
|
|
|
||
| ## Legacy Workers permissions | ||
|
|
||
| These legacy permissions are being replaced by the new Workers roles. There is no deprecation date right now. Existing permissions continue to work, and customers will receive advance notice before any deprecation. |
There was a problem hiding this comment.
| These legacy permissions are being replaced by the new Workers roles. There is no deprecation date right now. Existing permissions continue to work, and customers will receive advance notice before any deprecation. | |
| When granting access, you should use the new Workers roles above, and you should not use the legacy permissions below. While these legacy permissions continue to work, and they will be deprecated in the future. There is currently not a deprecation date, and customers will receive advance notice before any deprecation. |
to be explicit re: "you should use"
| @@ -0,0 +1,74 @@ | |||
| --- | |||
| title: R2 permissions and access | |||
There was a problem hiding this comment.
Should this be part of R2 docs instead? And if we need it to be discoverable, link to there?
|
|
||
| ## Workers roles | ||
|
|
||
| Workers roles can be assigned to members, User Groups, and API tokens. |
| | Editor | Edit | Can read, update, and deploy existing Workers, including script content, settings, routes, schedules, versions, deployments, and observability. Cannot create, delete, or rename Workers. | | ||
| | Admin | Full manage | Full control over Workers, including creating, reading, updating, deploying, deleting, and renaming Workers when granted at the product scope. Per-Worker Admin applies only to the selected Worker. | | ||
|
|
||
| ## Role scopes |
There was a problem hiding this comment.
is there a title that more loudly and explicitly signals something like "How to grant access to only some Workers"
|
|
||
| API tokens use the same Workers roles and scopes as members and User Groups, but they have their own permissions. A token can only perform actions allowed by the Workers role and scope assigned to that token. | ||
|
|
||
| ## Wrangler |
There was a problem hiding this comment.
should there be something in wrangler docs section about? or link to here?
irvinebroque
left a comment
irvinebroque
left a comment
There was a problem hiding this comment.
Deeplink to relevant part of dash will help people and agents here too
irvinebroque
left a comment
irvinebroque
left a comment
There was a problem hiding this comment.
How do I Terraform this? Can I do any of this via the API?
7 participants
Summary
Adds Developer Platform permissions documentation for the overview model, Workers role scopes, and R2 access options.
This is the first subset of authorization docs; additional product pages will be added in follow-up commits.
Screenshots (optional)
Documentation checklist