Secret Manager

Secrets are a type of binding that attach sensitive data like API keys, tokens, and passwords to your Worker. Unlike environment variables, secrets are encrypted at rest and in transit, providing secure storage for sensitive configuration data that your AI agents need.

Background

Secrets are available on the env parameter passed to your Worker's fetch event handler, just like environment variables. However, secrets are encrypted and designed specifically for sensitive data that should not be visible in logs or the Cloudflare dashboard after creation.

For non-sensitive configuration data like API endpoints and feature flags, use environment variables instead of secrets.

Add Secrets via Wrangler CLI

To add secrets using Wrangler, use the wrangler secret command. Secrets cannot be defined in the wrangler.json file for security reasons.

Setting Secrets

bash

Environment-Specific Secrets

Set secrets for specific environments using the --env flag:

bash

Wrangler Configuration

You must not setup env variables for secrets as they will conflcit when deploying your sevice!

Basic .dev.vars File

Your .dev.vars file will drive the generation of your env.d.ts file for static access to your secrets

bash

Agent Integration

Access secrets within your Agent class:

typescript

MCP Integration

Access secrets in your MCP Server:

typescript

Alternative Access via Node.js process.env

For Node.js compatibility, you can also access secrets through process.env by enabling the nodejs_compat_populate_process_env compatibility flag. This works the same way as environment variables.

⚠️ Critical Limitation: Like environment variables, process.env secrets are only available during runtime execution and cannot be accessed at module initialization time.

For complete details on Node.js compatibility, runtime limitations, and configuration examples, see the Node.js process.env section in Environment Variables.

Deploy to Specific Environments

Use the --env flag to deploy to specific environments which will use the specific secrets you have setup in your environment.

bash

Local Development with .dev.vars

For local development, add secrets to your .dev.vars file. This file should be formatted like a dotenv file and contains both environment variables and secrets for local development.

Environment-Specific .dev.vars Files

Create separate .dev.vars files for each environment during local development:

bash
bash

When you run wrangler dev --env staging, the .dev.vars.staging file will be loaded.

Important: Add .dev.vars* files to your .gitignore to prevent accidentally committing secrets:

gitignore

Code Generation for Type Safety

Secrets, environment variables, and service bindings are automatically generated as TypeScript types. In any agent or MCP project, run:

bash

This will automatically update the env.d.ts file with statically generated types for:

  • Environment variables from your wrangler.json configuration
  • Secrets from your .dev.vars file (for development) and Wrangler configuration
  • Service bindings and other Cloudflare bindings

Example generated types:

typescript

To ensure proper type generation:

  1. Add secrets to your .dev.vars file for local development
  2. Run npm run codegen to generate TypeScript types
  3. Set actual secrets using wrangler secret put for deployed environments

Secrets vs Environment Variables

Use Secrets For:

  • API keys and tokens
  • Database passwords
  • Encryption keys
  • Authentication credentials
  • Payment processing keys
  • Any sensitive data

Use Environment Variables For:

  • API endpoints and hostnames
  • Feature flags and configuration toggles
  • Non-sensitive limits and thresholds
  • Environment identifiers
  • Public configuration values

For non-sensitive information, use environment variables instead of secrets. Environment variables are visible in the Cloudflare dashboard and logs.

Practical Examples

Multi-Service Authentication

typescript

Secure Database Connection

typescript

Payment Processing

typescript

Environment-Aware Secret Usage

typescript

Best Practices

Security Guidelines

typescript

Error Handling

typescript

Security Features

  • Encryption: AES-256 encryption at rest, TLS 1.3 in transit
  • Access Control: Secrets are only accessible to your code at runtime
  • Audit Trail: Secret creation and deletion are logged
  • Zero Visibility: Secret values are never visible after creation
  • Environment Isolation: Secrets are isolated per environment

Limitations

  • Secret Size: Maximum 25KB per secret value
  • Secret Count: Maximum 100 secrets per Worker
  • Naming: Secret names must be valid environment variable names
  • CLI Only: Secrets can only be set via Wrangler CLI

Related Services

Official Documentation