← Secrets Store / secrets-store

Secrets Store access control

Secrets Store allows security administrators to have more control by implementing role-based access. For details about roles at Cloudflare, refer to Fundamentals.

Access to a secret is controlled by two independent checks that must both pass:

1. Authorization — the caller must have permission to perform the action. The permission comes from either a user role (when the dashboard authenticates the request) or an API token permission (when the request is made with an API token). A given request is evaluated against one or the other, not both.
2. Secret scope — the scope list on the secret must include the consuming service.

For example, deploying a Worker that binds a secret requires a role or API token that can bind secrets, and a secret whose scope includes workers.

Refer to the list below for default role definitions.

• Can create, edit, duplicate, delete, and view secrets metadata.
• Can add a Secrets Store binding to a Worker.
• Can create an association between a secret and an AI gateway.

• Can create, edit, duplicate, delete, and view secrets metadata.

• Can view secrets metadata but cannot create, edit, duplicate, nor delete secrets.
• Can add a Secrets Store binding to a Worker.
• Can create an association between a secret and an AI gateway.

• Can view secrets metadata.
• Cannot perform any actions (create, edit, duplicate, delete secrets), nor use Secrets Store integrations with other Cloudflare products.

API tokens have two Secrets Store permission levels: Read and Edit. The permission you need depends on what the token is doing, not on whether you intend to modify the secret itself.

• Account Secrets Store Read: Allows the caller to view metadata for secrets (for example, listing secrets or fetching the name, ID, scopes, and comments of a secret). This permission does not grant access to the value of a secret, and does not allow binding a secret to another resource.
• Account Secrets Store Edit: Allows the caller to create, edit, duplicate, or delete secrets. Edit is also required to bind a secret to another Cloudflare resource, such as adding a Secrets Store binding to a Worker or associating a secret with an AI Gateway. Attaching a secret to a resource is treated as a write against the secret.

Each secret has a list of scopes that determine which Cloudflare services are allowed to consume it. Scopes are set when a secret is created, and can be updated later by editing the secret.

The currently supported scopes are:

• workers — allows the secret to be bound to a Worker.
• ai-gateway — allows the secret to be associated with an AI Gateway.

A request to bind or associate a secret with a service will be rejected if that service is not in the scope list, even if the caller has the correct role or API token permission. Deploying a Worker with a Secrets Store binding therefore requires both:

• A user role or API token that can bind secrets (Super Administrator or Secrets Store Deployer role, or Account Secrets Store Edit API token permission).
• A scope list on the secret that includes workers.

You can set scopes when creating a secret using the dashboard, the API (scopes field), or Wrangler (--scopes flag).