Secrets Store and Version Management

Learning Focus

By the end of this lesson you will understand how to manage secrets securely and control deployment versions for your Workers.

Secrets Store

The Secrets Store provides a centralized, secure way to manage sensitive configuration values (API keys, tokens, database credentials) for your Workers.

Setting Secrets

Set a secret via Wrangler

# Set a secret (prompted for value)
wrangler secret put API_KEY

# Or via pipe
echo "my-secret-value" | wrangler secret put API_KEY

Using Secrets in Workers

src/index.ts

export interface Env {
  API_KEY: string;
  DATABASE_URL: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Secrets are accessed via the env object
    const response = await fetch("https://api.example.com/data", {
      headers: { "Authorization": `Bearer ${env.API_KEY}` },
    });

    return new Response(response.body);
  },
};

Secrets vs Environment Variables

Feature	Secrets	Environment Variables
Stored in	Encrypted, not in wrangler.toml	Plain text in wrangler.toml
Visible in dashboard	❌ Hidden after creation	✅ Visible
Git-safe	✅ Never committed to source control	❌ In wrangler.toml (could be in Git)
Use for	API keys, tokens, passwords	Non-sensitive config (URLs, feature flags)

wrangler.toml — Environment variables (non-secret)

[vars]
API_URL = "https://api.example.com"
ENVIRONMENT = "production"

# Secrets are NOT stored here — they're set via `wrangler secret put`

Best Practice

Never put sensitive values in wrangler.toml or environment variables. Always use wrangler secret put for API keys, tokens, and credentials.

Version Management

Version Management lets you control how new Worker code is deployed, with the ability to gradually roll out changes and instantly roll back if issues are detected.

Deployments

Every wrangler deploy creates a new version. You can view and manage versions in the dashboard:

1. Go to Workers & Pages → Your Worker → Deployments
2. See a list of all deployed versions
3. Rollback to any previous version with one click

Gradual Rollouts

On paid plans, you can deploy a new version to a percentage of traffic:

Version A (current): 90% of traffic
Version B (new):     10% of traffic

As confidence grows, increase the percentage until the new version handles 100%.

On the Free Plan

The free plan includes:

• Version history — see all previous deployments
• Instant rollback — revert to any previous version
• Deployment logs — track when each version was deployed

Key Takeaways

• Use the Secrets Store for all sensitive values — API keys, tokens, credentials.
• Secrets are encrypted and never visible after creation.
• Version Management provides deployment history and instant rollback.
• Set secrets with wrangler secret put — never in wrangler.toml.
• Free plan includes version history and rollback; paid plans add gradual rollouts.

What's Next

• Continue to Analytics and Observability to learn about monitoring your Cloudflare traffic.