Skip to content

[Workers, R2] Add permissions access docs #31672

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dinasaur404 wants to merge 3 commits into
base: production
Choose a base branch
from
+303 −0
Draft

[Workers, R2] Add permissions access docs #31672

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ceeb6eb
[Workers, R2] Add permissions access docs
dinasaur404 Jun 24, 2026
48859af
Fixed PR #31672 review feedback.
ask-bonk[bot] Jun 24, 2026
e5d69d2
[Workers] Clarify Wrangler authorization
dinasaur404 Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions src/content/docs/workers/authorization/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
title: Permissions and access
description: Learn how Developer Platform permissions apply across platform, product, and resource scopes.
pcx_content_type: concept
sidebar:
order: 8.5
products:
- workers
---

You can control who can access your Developer Platform resources and what they can do with them by assigning [roles](/fundamentals/manage-members/roles/) and [scopes](/fundamentals/manage-members/scope/) through [permission policies](/fundamentals/manage-members/policies/). Each policy combines a role, which defines the actions allowed, with a scope, which defines where those actions apply.

For Developer Platform products, scopes can be set at three levels:

| Level | Scope | Use when |
| -------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Platform | All products on an account | You want to grant access across Workers, R2, D1, KV, Durable Objects, Queues, Workers AI, Vectorize, Hyperdrive, and other Developer Platform resources. |
| Product | All resources in one product | You want to grant access to all Workers, all R2 buckets, or all D1 databases, without granting access to other products. |
| Resource | One resource inside a product | You want to grant access to a specific resource, such as an individual Worker or R2 bucket. |

## Roles

Assign one of these roles to define the level of permission you want to grant:

| Role | What it allows |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Metadata Read-Only | View resource lists, settings, metrics, logs, and traces. Cannot view product content such as code, data, or stored objects. |
| Content Read-Only | Everything in Metadata Read-Only, plus read product content such as Worker code, D1 database rows, or R2 objects. Cannot make changes. |
| Editor | Everything in Content Read-Only, plus update product content and settings. Cannot create, delete, or rename resources. |
| Admin | Full control, including creating, deleting, and renaming resources. |

## Members, User Groups, and API tokens

Developer Platform permissions can be granted in two ways:

| Grant type | Best for | How it works |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| [Members](/fundamentals/manage-members/manage/) and [User Groups](/fundamentals/manage-members/user-groups/) | People using the dashboard, Wrangler, or the API | Permissions are inherited when the member signs in to the Cloudflare dashboard or authenticates Wrangler. |
| [API tokens](/fundamentals/api/get-started/create-token/) | CI/CD systems, automation, and service accounts | The token receives only the product and resource permissions selected when the token is created. |

### Members and User Groups

When you assign a [role](/fundamentals/manage-members/roles/) to a [member](/fundamentals/manage-members/manage/) or [User Group](/fundamentals/manage-members/user-groups/), that permission applies whenever the user uses the Cloudflare dashboard, Wrangler, or the API.

For example, if you assign a member **Metadata Read-Only** at the platform level, they can view settings, metrics, logs, and traces for all Developer Platform products on the account — Workers, R2, D1, and everything else — but cannot view product content like code, data, or stored objects.

If you assign **Metadata Read-Only** at the Workers product level, they can view settings and observability data for all Workers on the account, but have no visibility into R2, D1, or other products.

If you assign **Metadata Read-Only** for a single Worker, they can only see settings and observability data for that one Worker. They will not see any other Workers or any other products.

### API tokens

Use [API tokens](/fundamentals/api/get-started/create-token/) for CI/CD pipelines, agents, scripts, and other automated systems that need to access Developer Platform resources programmatically.

For example, create an API token with **Workers Editor** for a deployment pipeline that needs to update and deploy Worker code.

API tokens support product-level and, where available, resource-level permissions. They do not support platform-level permissions. To grant an API token broad Developer Platform access, select the product-level permissions for each product the token needs.

### Use Wrangler with member or token authentication

[Wrangler](/workers/wrangler/) authorizes commands using the permissions of the authenticated member or API token.

For interactive use, run [`wrangler login`](/workers/wrangler/commands/general/#login). Wrangler uses the roles and scopes assigned to your member account.

For CI/CD pipelines, agents, scripts, and other automated systems, use an API token instead of a member login. Create a token with only the permissions the system needs, then set these environment variables before running Wrangler:

```bash
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export CLOUDFLARE_ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
```

Wrangler uses the token's permissions. If the token is scoped to a specific Worker, Wrangler can only perform actions allowed for that Worker.

Wrangler commands can require different permissions depending on what they manage:

| What you want to do | Example Wrangler command | Required access |
| --------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Deploy an existing Worker | `wrangler deploy` | `Editor` scoped to that Worker, or `Editor` at the Workers product scope. |
| Create a new Worker | `wrangler deploy` for a Worker that does not exist yet | `Admin` at the Workers product scope. |
| Tail logs for one Worker | `wrangler tail` | `Metadata Read-Only` scoped to that Worker, or `Metadata Read-Only` at the Workers product scope. |
| List KV namespaces | `wrangler kv namespace list` | Developer Platform `Metadata Read-Only` at a scope that includes KV. |
| Create a KV namespace | `wrangler kv namespace create` | Developer Platform `Admin` at a scope that includes KV. |
| Deploy a Worker with routes | `wrangler deploy` | `Editor` for the Worker, plus the [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains/) for routes. |

## Bindings

To deploy a Worker that has [bindings](/workers/runtime-apis/bindings/) to resources like [Workers KV](/kv/), [R2](/r2/), or [D1](/d1/), you need **Editor** access to the Worker. You do not need separate permissions on the bound resources to deploy the Worker.

Permissions on bound resources are only required if you need to access those resources directly, for example, reading KV keys, querying a D1 database, or listing R2 objects.

## Common access patterns

| Use case | Scope | Role |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| View settings, logs, and metrics across all products | Platform | Metadata Read-Only |
| Read Worker code without modifying it | Workers product | Content Read-Only |
| Deploy any existing Worker, no access to other products | Workers product | Editor |
| Deploy a Worker that uses routes | Workers product and [domain-level permissions](/fundamentals/manage-members/scope/#specific-domains) for each domain referenced by the routes | Editor |
| Create or delete Workers | Workers product | Admin |
| Automated deployments from CI/CD or agents | API token with Workers product | Editor |
| Automated deployments to one specific Worker | API token with individual Worker | Editor |
74 changes: 74 additions & 0 deletions src/content/docs/workers/authorization/r2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: R2 permissions and access

@irvinebroque irvinebroque Jun 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be part of R2 docs instead? And if we need it to be discoverable, link to there?

description: Learn how to manage R2 access through member roles, R2 API tokens, and account API token permission groups.
pcx_content_type: reference
sidebar:
order: 16
products:
- workers
---

[R2](/r2/) permissions control who or what can read, edit, and manage [buckets](/r2/buckets/), [objects](/r2/objects/), warehouses, and associated configuration in your Cloudflare account. Access is granted by assigning an R2 role or permission to a [member](/fundamentals/manage-members/manage/), [User Group](/fundamentals/manage-members/user-groups/), or [API token](/fundamentals/api/get-started/create-token/).

## Members and User Groups

Use R2 roles when a person needs dashboard or user-based access.

| Role | Access |
| ------------------- | -------------------------------------------------------------------- |
| Cloudflare R2 Read | Read R2 buckets, objects, warehouses, and associated configurations. |
| Cloudflare R2 Admin | Edit R2 buckets, objects, warehouses, and associated configurations. |

## API tokens

R2 has two types of API tokens. Choose based on how your application connects to R2:

| How you access R2 | Token type to create |
| ------------------------------------------------------------------------------------ | -------------------- |
| S3-compatible SDKs, CLI tools, or [S3 API](/r2/api/s3/) calls | R2 API token |
| [Cloudflare API](/api/), [Wrangler](/workers/wrangler/), or [Terraform](/terraform/) | Account API token |

To create an R2 API token, refer to [R2 API tokens](/r2/api/tokens/). To create an account API token, refer to [Create API tokens](/fundamentals/api/get-started/create-token/).

### R2 API tokens

Use R2 API tokens when an application needs S3-compatible access to R2.

| Permission | Scope | Access |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin Read & Write | Account | Create, list, and delete buckets, edit bucket configuration, read, write, and list objects, and read and write to data catalog tables and associated metadata. |
| Admin Read only | Account | List buckets and view bucket configuration, read and list objects, and read from data catalog tables and associated metadata. |
| Object Read & Write | Bucket | Read, write, and list objects in selected buckets. |
| Object Read only | Bucket | Read and list objects in selected buckets. |

Account-scoped permissions apply to all buckets. Bucket-scoped permissions apply only to the buckets you select when creating the token.

:::note
[R2 Data Catalog](/r2/data-catalog/) currently requires `Admin Read & Write` or `Admin Read only`.
:::

### Account API token permission groups

Use account API token permission groups when an automated system needs access to R2 through the Cloudflare API.

**Storage**

| Permission group | Scope | Access |
| ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------- |
| Workers R2 Storage Read | Account | List buckets, view bucket configuration, and read and list objects. |
| Workers R2 Storage Write | Account | Create, delete, and list buckets, edit bucket configuration, and read, write, and list objects. |
| Workers R2 Storage Bucket Item Read | Bucket | Read and list objects in buckets. |
| Workers R2 Storage Bucket Item Write | Bucket | Read, write, and list objects in buckets. |

**Data Catalog**

| Permission group | Scope | Access |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| Workers R2 Data Catalog Read | Account | Read from data catalogs through the [Iceberg REST catalog interface](/r2/data-catalog/). |
| Workers R2 Data Catalog Write | Account | Read from and write to data catalogs through the [Iceberg REST catalog interface](/r2/data-catalog/). |

**SQL**

| Permission group | Scope | Access |
| ------------------- | ------- | ---------------------------------- |
| Workers R2 SQL Read | Account | Read [R2 SQL](/r2-sql/) resources. |
Loading