Secrets

Background

Secrets are a type of binding that allow you to attach encrypted text values to your Worker. Secrets are used for storing sensitive information like API keys and auth tokens.

You can access secrets in your Worker code through:

• The env parameter passed to your Worker's fetch event handler.
• Importing env from cloudflare:workers to access secrets from anywhere in your code.
• process.env in Workers that have Node.js compatibility enabled.

Access your secrets with Workers

Secrets can be accessed from Workers as you would any other environment variables. For instance, given a DB_CONNECTION_STRING secret, you can access it in your Worker code through the env parameter:

import postgres from "postgres";

export default {
	async fetch(request, env, ctx) {
		const sql = postgres(env.DB_CONNECTION_STRING);

		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

You can also import env from cloudflare:workers to access secrets from anywhere in your code, including outside of request handlers:

import { env } from "cloudflare:workers";
import postgres from "postgres";

// Initialize the database client at the top level using a secret
const sql = postgres(env.DB_CONNECTION_STRING);

export default {
	async fetch(request: Request): Promise<Response> {
		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

For more details on accessing env globally, refer to Importing env as a global.

:::note[Secrets Store (beta)] Secrets described on this page are defined and managed on a per-Worker level. If you want to use account-level secrets, refer to Secrets Store. Account-level secrets are configured on your Worker as a Secrets Store binding. :::

Local Development with Secrets

Secrets on deployed Workers

Validate secrets before deploy

You can declare the secret names your Worker requires using the secrets configuration property in your Wrangler configuration. When defined, wrangler deploy and wrangler versions upload will fail with a clear error if any required secrets are not configured on the Worker.

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.

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 deployed using wrangler versions deploy.

:::note Wrangler versions before 3.73.0 require you to specify a --x-versions flag. :::

npx wrangler versions secret put <KEY>

Via the dashboard

To add a secret via the dashboard:

1. In the Cloudflare dashboard, go to the Workers & Pages page.

https://dash.cloudflare.com/?to=/:account/workers-and-pages

2. In Overview, select your Worker > Settings.
3. Under Variables and Secrets, select Add.
4. 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.
5. (Optional) To add more secrets, select Add variable.
6. Select Deploy to implement your changes.

Upload secrets alongside code

You can upload secrets at the same time as your Worker code using the --secrets-file flag on wrangler deploy or wrangler versions upload. This accepts a path to a JSON or .env file — the same formats accepted by wrangler secret bulk. You can upload up to 100 secrets per bulk request for a single version.

npx wrangler deploy --secrets-file .env.production

npx wrangler versions upload --secrets-file secrets.json

Secrets not included in the file are preserved from the previous version. This is useful in CI/CD pipelines where you want to deploy code and update secrets in a single operation.

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.

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 deployed using wrangler versions deploy.

npx wrangler versions secret delete <KEY>

Via the dashboard

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

1. In the Cloudflare dashboard, go to the Workers & Pages page.

https://dash.cloudflare.com/?to=/:account/workers-and-pages

2. In Overview, select your Worker > Settings.
3. Under Variables and Secrets, select Edit.
4. In the Edit drawer, select X next to the secret you want to delete.
5. Select Deploy to implement your changes.
6. (Optional) Instead of using the edit drawer, you can click the delete icon next to the secret.

Related resources

• Wrangler secret commands - Review the Wrangler commands to create, delete and list secrets.
• secrets configuration property - Declare required secret names in your Wrangler configuration. Used for validation during local development and deploy, and as the source of truth for type generation.
• Cloudflare Secrets Store - Encrypt and store sensitive information as secrets that are securely reusable across your account.