---
title: "Rotate a secret"
description: "See which secrets the app declares, rotate one without a restart, and keep verifying with the old value during the overlap."
section: "guides"
status: "Planned for 0.3"
spec: "secret-rotation"
canonical: "https://mainsdk.dev/docs/guides/rotate-a-secret"
updated: "2026-10-28"
---

# Rotate a secret

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

Status: Planned for 0.3 · Canonical: https://mainsdk.dev/docs/guides/rotate-a-secret · 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

```ts title="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.

## Next

- [Secrets reference](https://mainsdk.dev/docs/interfaces/secrets)
- [Check codes](https://mainsdk.dev/docs/reference/check-codes)