Rotate a secret

See which secrets the app declares, rotate one without a restart, and keep verifying with the old value during the overlap.

Planned for 0.3

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

You will list your secrets, rotate one and see the old value stop working after the overlap. It takes about 10 minutes.

You need

A MainSDK app with secret: references in main.yaml.

1. See what is set

bash

npx mainsdk secrets status --env prod

Each declared secret is listed with whether it is set. A missing value is MAIN-SECRET-0005.

2. Rotate one

bash

npx mainsdk secrets rotate PARTNER_API_TOKEN --env prod

The running app picks up the new value within secrets.ttl, so it needs no restart.

3. Verify with both values

app/api/webhook/route.ts

import { secrets } from "mainsdk/secrets";

const [current, previous] = await secrets.all("PARTNER_API_TOKEN");

secrets.all(name) returns the current value first, and the previous one only while the rotation.overlap has not passed. Check a signature against each in order, and sign only with the current value.

Check that it works

secrets.age("PARTNER_API_TOKEN") shows the new version and stale: false.
After the overlap, secrets.all returns one value.

Was this page helpful?

You need

1. See what is set

2. Rotate one

3. Verify with both values

Check that it works

Next