Use a Worker secret for API credentials and other sensitive values. A secret binding keeps the value out of ordinary visible configuration, but the Worker code must still avoid returning or logging it.
IN THIS ARTICLE
What you need before you begin
Identify the exact Worker and environment that needs the credential. Create a narrowly scoped upstream token and prepare a rotation plan. Keep local development secrets out of source control.
01 Store a Worker secret without exposing it in code
- Open Workers & Pages, select the Worker and open Settings.
- Under Variables and Secrets, add a value of type Secret with a clear variable name.
- Deploy the change using the supported workflow and read the binding from the Worker’s environment, such as
env.API_TOKENin a module Worker. - Test the intended upstream request without printing the secret, entire environment object or sensitive authorisation headers.
- Rotate by installing a replacement, verifying the new credential and then revoking the old upstream token. Review preview or development environments separately.
02 Example: prepare a staging secret without publishing it in code
From the correct Worker project, with its staging environment already configured, this current Wrangler workflow prompts for the secret value and creates a new Worker version. It does not deploy that version automatically.
npx wrangler versions secret put API_TOKEN --env stagingEnter the credential only at the protected prompt, then review the resulting version in your normal deployment workflow. The application reads the binding through env.API_TOKEN and must not print it. Ordinary wrangler secret put has different behaviour: it immediately deploys a new version.
For local development, keep secret files out of source control. The relevant .gitignore entries are:
.dev.vars*
.env*Expected result: the intended environment receives the binding through a deliberate release. Ignore rules do not remove a secret already committed to history; replace any exposed credential. Verify the replacement before revoking the previous upstream token.
Confirm the expected result
The Worker should access the required service using its secret binding, while client responses, logs and repositories contain no credential value.
Troubleshoot unexpected results
A plaintext variable is not the right place for a password. Local .dev.vars or .env files also need ignore rules and protected storage. Secret updates and deployment/version workflows can affect active code, so review the target environment before applying them.
Can I safely return a secret in a debug response because it is encrypted in settings?
No. Encryption at storage does not protect a value that your own code sends to a visitor or log. Treat the runtime value as sensitive throughout the request.