When a team moves a payment provider key from per-Worker secrets into Cloudflare Secrets Store, what changes in configuration, permissions and Worker code?
answer
- account-level, bound per Worker
- the secrets_store_secrets entry
- scopes and the Deployer role
- await get() on the binding
basics
~20 sThe key becomes one account-level secret bound into each Worker through secrets_store_secrets. Binding needs a role or token that can bind plus the workers scope, and code reads it with await env.PROVIDER_KEY.get() instead of a string.
solid answer
~50 sSecrets Store, in beta as of 2026-10-10, holds account-level secrets: the key is created once, for example with `wrangler secrets-store secret create <STORE_ID> --name payments-provider-api-key --scopes workers --remote`, and each Worker that needs it adds a `secrets_store_secrets` entry with `binding`, `store_id` and `secret_name`. Two checks must pass to bind it: the secret's scopes must include `workers`, and the deployer needs a role that can bind (Super Administrator or Secrets Store Deployer) or, in CI, an API token with **Account Secrets Store Edit**, because binding counts as a write; a Read-only token fails the deploy with an authorization error. In code the binding is no longer a string: `await env.PROVIDER_KEY.get()` resolves to the value and throws if the secret does not exist, so every reader of the old string must change. The beta allows one store and up to 100 production secrets per account.
code
bash · 2 linesnpx wrangler secrets-store store list --remote
npx wrangler secrets-store secret create 8f7e6d5c4b3a29180f7e6d5c4b3a2918 --name payments-provider-api-key --scopes workers --remotego deeper
Recall that Secrets Store holds account-level secrets and that a Worker reads one with await env.NAME.get() rather than as a string.
Explain the binding, store_id and secret_name fields and the two checks behind a bind: a role or token that can bind, and the workers scope.
Plan the move: create the secret, give CI an Edit token, bind it, switch every reader to await get(), then delete the old per-Worker secrets.
Decide which credentials become account-level and who holds the Admin and Deployer roles, weighing shared reuse against a beta with per-account limits.
## Two places a secret can live A **per-Worker secret** belongs to one Worker: it is set with `wrangler secret put`, and the Worker reads it as a plain string on `env`. **Cloudflare Secrets Store** holds **account-level secrets**: a secret is created once in the account's store and attached, through a binding, to every Worker that needs it. A payment provider key used by a webhook Worker, a refunds Worker and a reconciliation Worker is the typical case: one value, one place to replace it, many consumers. With per-Worker secrets the same key would be pasted into three Workers, each with its own `wrangler secret put`, and replacing it means remembering all three. With Secrets Store the value is changed in one place and every bound Worker reads it through its binding. The store also serves other products: the same secrets can be associated with an AI gateway when their scope allows it. | | Per-Worker secret | Secrets Store secret | |---|---|---| | Lives on | One Worker | The account's store | | Created with | `wrangler secret put`, the dashboard | `wrangler secrets-store secret create`, the dashboard, the API | | Wrangler config | None | A `secrets_store_secrets` entry | | Read in code | `env.PROVIDER_API_KEY` (a string) | `await env.PROVIDER_KEY.get()` | | Size and count | 5 KB each; 64 or 128 vars and secrets per Worker | Up to 65,536 bytes each; 100 production secrets per account | | Status | Part of Workers | Beta | ## Configuration The secret is created with the `workers` scope, then bound under a name of the team's choosing: ```json { "secrets_store_secrets": [ { "binding": "PROVIDER_KEY", "store_id": "8f7e6d5c4b3a29180f7e6d5c4b3a2918", "secret_name": "payments-provider-api-key" } ] } ``` `binding` is the property name on `env`; `store_id` and `secret_name` identify the account secret. Once saved, the secret's value cannot be viewed again in the dashboard. ## Permissions: two independent checks Binding a secret to a Worker passes only when both of these hold: 1. **Authorization.** The caller's role (dashboard) or API token permission (Wrangler, CI) must allow binding: - **Super Administrator**: can create, edit and delete secrets, and bind them. - **Secrets Store Admin**: can create, edit, duplicate and delete secrets and view metadata; it is not among the roles listed as able to bind. - **Secrets Store Deployer**: can bind secrets to Workers and view metadata, but cannot create, edit or delete secrets. - **Secrets Store Reporter**: can view metadata only. - For tokens, **Account Secrets Store Read** covers metadata only; **Account Secrets Store Edit** is required to bind, because attaching a secret counts as a write against it. 2. **Scope.** The secret's scope list must include `workers` (the other current scope is `ai-gateway`). A bind is rejected without it, whatever the caller's permissions. A CI pipeline whose token has only Read fails at deploy time with an error such as `failed to fetch secrets store binding due to authorization error - check deploy permissions and secret scopes`. The role split gives a security team separation of duties: admins own the values, deployers attach existing secrets without being able to plant or change one, and nobody can read a value back after it is saved. ## Code changes The binding is an object of type `SecretsStoreSecret` with one method, `get(): Promise<string>`. It resolves to the value and **throws if the secret does not exist**, so: - every place that used `env.PROVIDER_API_KEY` as a string must now `await env.PROVIDER_KEY.get()`; - a reader that interpolates the binding itself into a header sends the object's string form, not the key; - the call belongs in a `try` block with a deliberate failure response; - `process.env` does not carry it, because Node.js compatibility fills `process.env` from text bindings only. Locally, production secrets are not reachable; local development uses secrets created without `--remote`, which the local development material covers. ## A migration order that avoids an outage 1. Create the account secret with the `workers` scope. 2. Give the deploying identity the right to bind: **Account Secrets Store Edit** on a CI token, or the Super Administrator or Secrets Store Deployer role for someone binding in the dashboard. 3. Add the `secrets_store_secrets` binding and change every reader to `await get()`, in one deploy. 4. Confirm the Workers serve traffic with the new binding. 5. Remove the old per-Worker secrets with `wrangler secret delete`.
- Why does a CI deploy fail after adding a Secrets Store binding when the same pipeline deployed fine before?Binding a secret counts as a write against it, so the pipeline's API token needs **Account Secrets Store Edit**; a token with only Read fails with `failed to fetch secrets store binding due to authorization error - check deploy permissions and secret scopes`. As the message says, also check that the secret's scopes include `workers`.
- What does splitting Secrets Store Admin from Secrets Store Deployer buy a security team?Separation of duties: admins create and change secret values, deployers attach existing secrets to Workers but cannot create, edit or delete them, and nobody reads a value back once it is saved. Someone holding only the Deployer role can bind what exists but cannot plant or alter a key.
- Reading env.PROVIDER_KEY as a string after moving the key into Secrets Store.
- Giving the CI token only Secrets Store Read because it never changes secret values.
- Creating the account secret without the workers scope and expecting it to bind.
- Expecting the dashboard to show an account secret's value after it is saved.
- Assuming wrangler dev reads production Secrets Store values by default.
As of 2026-10-10 Secrets Store is in beta, with one store per account and up to 100 production secrets per account; per-Worker secrets are unaffected by those limits.