Skip to content
Cloudflare Docs

Secrets

Background

Secrets are a type of binding that allow you to attach encrypted text values to your Worker. You cannot see secrets after you set them and can only access secrets via Wrangler or programmatically via the env parameter. Secrets are used for storing sensitive information like API keys and auth tokens. Secrets are available on the env parameter passed to your Worker's fetch event handler.

Local Development with Secrets

When developing your Worker or Pages Function, create a .dev.vars file in the root of your project to define secrets that will be used when running wrangler dev or wrangler pages dev, as opposed to using environment variables in the Wrangler configuration file. This works both in local and remote development modes.

The .dev.vars file should be formatted like a dotenv file, such as KEY="VALUE":

.dev.vars
SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

To set different secrets for each environment, create files named .dev.vars.<environment-name>. When you use wrangler <command> --env <environment-name>, the corresponding environment-specific file will be loaded instead of the .dev.vars file, so the two files are not merged.

Like other environment variables, secrets are non-inheritable and must be defined per environment.

Secrets on deployed Workers

Adding secrets to your project

Via Wrangler

Secrets can be added through wrangler secret put or wrangler versions secret put commands.

wrangler secret put creates a new version of the Worker and deploys it immediately.

Terminal window
npx wrangler secret put <KEY>

If using gradual deployments, instead use the wrangler versions secret put command. This will only create a new version of the Worker, that can then be deploying using wrangler versions deploy.

Terminal window
npx wrangler versions secret put <KEY>

Via the dashboard

To add a secret via the dashboard:

  1. Log in to Cloudflare dashboard ↗ and select your account.
  2. Select Workers & Pages.
  3. In Overview, select your Worker > Settings.
  4. Under Variables and Secrets, select Add.
  5. Select the type Secret, input a Variable name, and input its Value. This secret will be made available to your Worker but the value will be hidden in Wrangler and the dashboard.
  6. (Optional) To add more secrets, select Add variable.
  7. Select Deploy to implement your changes.

Delete secrets from your project

Via Wrangler

Secrets can be deleted through wrangler secret delete or wrangler versions secret delete commands.

wrangler secret delete creates a new version of the Worker and deploys it immediately.

Terminal window
npx wrangler secret delete <KEY>

If using gradual deployments, instead use the wrangler versions secret delete command. This will only create a new version of the Worker, that can then be deploying using wrangler versions deploy.

Terminal window
npx wrangler versions secret delete <KEY>

Via the dashboard

To delete a secret from your Worker project via the dashboard:

  1. Log in to Cloudflare dashboard ↗ and select your account.
  2. Select Workers & Pages.
  3. In Overview, select your Worker > Settings.
  4. Under Variables and Secrets, select Edit.
  5. In the Edit drawer, select X next to the secret you want to delete.
  6. Select Deploy to implement your changes.
  7. (Optional) Instead of using the edit drawer, you can click the delete icon next to the secret.

Secrets vs Environment Variables

When to use secrets

If your environment variable is a secret (such as a password or API token), select the Secret type when adding it via the dashboard or use Wrangler's built-in command:

Terminal window
 wrangler secret put <KEY>

Secrets function similarly to environment variables in a Worker, but with crucial differences:

  • Visibility: Once you define a secret, its value is no longer visible in Wrangler or the Cloudflare dashboard.

  • Security: Sensitive data, such as passwords and tokens, should always be encrypted to prevent accidental exposure.

To your Worker, there is no difference between an environment variable and a secret. The secret's value is passed through as defined.

When to use plaintext environment variables

Plaintext environment variables are best for non-sensitive configuration details, such as hostnames and IDs. These are values that do not require encryption because leaking them does not compromise security or privacy.