Rotation

Secret rotation is declared with the product so the compiler, deployment records, and local rotation command all understand the same intent.

Rotation Interval

Use rotation.everyDays to declare the target interval:

const sessionKey = secret.random({
  name: "session-key",
  namespace: "auth",
  rotation: {
    everyDays: 30,
  },
})

The minimum interval is 7 days.

You can also schedule the first rotation anchor:

const sessionKey = secret.random({
  name: "session-key",
  namespace: "auth",
  rotation: {
    everyDays: 30,
    startAt: "2026-06-01T00:00:00.000Z",
  },
})

Retention Modes

Retention controls how old versions remain readable.

Current Value Only

Use none for secrets where rotation should keep only the latest value:

const providerKey = secret.random({
  name: "provider-key",
  namespace: "billing",
  rotation: {
    everyDays: 30,
    retain: {
      mode: "none",
    },
  },
})

Temporary Overlap

Use retain_for for signing keys, login tokens, cookies, and webhook verification keys where old values must remain valid for a short window:

const sessionKey = secret.random({
  name: "session-key",
  namespace: "auth",
  rotation: {
    everyDays: 30,
    retain: {
      mode: "retain_for",
      days: 14,
    },
  },
})

During the overlap window, active() returns every value that can validate existing data:

const activeKeys = await sessionKey.active()

Permanent History

Use retain_forever for encryption keys used with stored data:

const encryptionKey = secret.random({
  name: "encryption-key",
  namespace: "storage",
  rotation: {
    everyDays: 90,
    retain: {
      mode: "retain_forever",
    },
  },
})

Read the correct version with metadata saved beside the encrypted value:

const key = await encryptionKey.version(record.keyVersion).bytes()

Or read by timestamp:

const key = await encryptionKey.at(record.encryptedAt).bytes()

Direct Cloudflare Deploy

Direct Cloudflare deploys can use values already written to Cloudflare Secrets Store:

layer secret set SESSION_KEY --value-env SESSION_KEY

Use secret rotate to check generated secrets with rotation intent:

layer secret rotate --env production

Use --apply --yes when the command should write due rotations:

layer secret rotate --env production --apply --yes

The command compiles the local app, reads generated Secret resources, checks the local rotation journal, and writes due values to the user’s Cloudflare Secrets Store. Product Workers only read their Secrets Store bindings. Cloudflare credentials stay in the local CLI process.

Add the apply command to cron when local direct deploys should rotate on a schedule.

Rotation State

The local CLI stores generated rotation metadata under the project .layeron directory. Version retention uses one Cloudflare secret value with the versioned JSON format documented in Values And Versioning.

Product-specific generated values can require a product-specific provider flow. The check output marks those entries when a generic Secret rotation value cannot preserve the product credential shape.