Use Secrets Store with Workers

Cloudflare Secrets Store is a secure, centralized location in which account-level secrets are stored and managed. The secrets are securely encrypted and stored across all Cloudflare data centers.

Consider the steps below to learn how to use values from your account secrets store with Cloudflare Workers.

Note

This is different from Workers Variables and Secrets, where you define and manage your secrets on a per-Worker level.

Before you begin

• If using the Dashboard, make sure you already have a Workers application. Refer to the Workers get started for guidance.

• You should also have a store created under the Secrets Store tab on the Dashboard. The first store in your account is created automatically when a user with Super Administrator or Secrets Store Admin role interacts with it.

  • If no store exists in your account yet and you have the necessary permissions, you can use the Wrangler command secrets-store store create <name> --remote to create your first store.

Local development mode

This guide assumes you are working in production. To use Secrets Store locally, you must use secrets-store secret Wrangler commands without the --remote flag.

1. Set up account secrets in Secrets Store

Follow the steps below to create secrets. You must have a Super Administrator or a Secrets Store Admin role within your Cloudflare account.

Note

You may also add account secrets directly from the Workers settings on the dashboard. You can skip to step 2 to do that.

Wrangler

Use the Wrangler command secrets-store secret create.

To use the following example, replace the store ID and secret name by your actual data. You can find and copy the store ID from the Secrets Store tab ↗ on the dashboard or use wrangler secrets-store store list.

Note that a secret name cannot contain spaces.

npx wrangler secrets-store secret create <STORE_ID> --name MY_SECRET_NAME --scopes workers --remote

✓ Enter a secret value: › ***

🔐 Creating secret... (Name: MY_SECRET_NAME, Value: REDACTED, Scopes: workers, Comment: undefined)
✓ Select an account: › My account
✅ Created secret! (ID: 13bc7498c6374a4e9d13be091c3c65f1)

Dashboard

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Secrets Store and select Create secret.
3. Fill in the required fields, choosing Workers as the Permission scope. Once the secret is saved, the secret value will no longer be available for viewing.
4. (Optional) Select Add additional secret to create more than one secret at a time.
5. Select Save to confirm.

API

You can find and copy the store ID from the Secrets Store tab ↗ on the dashboard or use the Wrangler command. Also, make sure your secret name does not contain spaces.

Refer to Secrets Store API for the full API documentation.

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores/$STORE_ID/secrets \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '[
  {
    "name":"<MY_SECRET_NAME>",
    "value":"<SECRET_VALUE>",
    "scopes":["workers"],
    "comment":""
  },
  {
    "name":"<MY_SECRET_NAME_2>",
    "value":"<SECRET_VALUE>",
    "scopes":["workers"],
    "comment":""
  }
]'

Refer to manage account secrets for further options.

2. Bind an account secret to your Worker

Bindings allow your Worker to interact with resources on your Cloudflare account.

To bind an account secret to your Worker, you must have one of the following roles within your Cloudflare account:

• Super Administrator
• Secrets Store Deployer

Via Wrangler

1. Add a Secrets Store binding to your Wrangler configuration file:
   • binding: a descriptive name for your binding. This will be used in the Workers application when accessing your secret on the env object.
   • store_id: the corresponding Secrets Store ID where your account secret was created.
   • secret_name: the unique secret name, defined when your account secret was created.

wrangler.jsonc

{
  "main": "./src/index.js",
  "secrets_store_secrets": [
    {
      "binding": "<BINDING_VARIABLE>",
      "store_id": "<STORE_ID>",
      "secret_name": "<MY_SECRET_NAME>"
    }
  ]
}

wrangler.toml

main = "./src/index.js"
secrets_store_secrets = [
  { binding = "<BINDING_VARIABLE>", store_id= "<STORE_ID>", secret_name = "<MY_SECRET_NAME>" }
]

Via Dashboard

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Workers & Pages and select a Workers application.
3. Go to Settings > Bindings and select Add.
4. On the Add a resource binding side panel, choose Secrets Store.
5. Fill in the required fields:
   • Variable name: a name for the binding. This will be used for your Worker to access the secret (step 3 below).
   • Secret name: select from the list of available account secrets created in step 1.
   • (Optional - Admins only) If the secret you need does not exist yet, select Create secret. This will add an account level secret in the same way as if you had created it on the Secrets Store.
6. Select Deploy to deploy your binding. When deploying, there are two options:
   • Deploy: Immediately deploy the binding to 100% of your audience.
   • Save version: Save a version of the binding which you can deploy in the future.

3. Access the secret on the env object

Bindings are located on the env object. To access the secret you first need an asynchronous call.

Call get() on the binding variable

Local development mode

You cannot access production secrets (created on the dashboard, via API, or with the --remote flag) from your local development setup. To use Secrets Store locally, you must use secrets-store secret Wrangler commands without the --remote flag.

export default {
  async fetch(request, env) {
    // Example of using the secret safely in an API request
    const APIkey = await env.<BINDING_VARIABLE>.get()

    const response = await fetch("https://api.example.com/data", {
      headers: { "Authorization": `Bearer ${APIKey}` },
    });

    if (!response.ok) {
      return new Response("Failed to fetch data", { status: response.status });
    }

    const data = await response.json();
    return new Response(JSON.stringify(data), {
      headers: { "Content-Type": "application/json" },
    });
  },
};