> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudraid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate a compromised secret

> Replace a leaked or aging agent secret without breaking traffic.

If an agent's secret is exposed — committed by accident, leaked in a log, or just old — replace it. Rotation issues a new secret while keeping the old one working briefly, so you can swap without an outage.

## When to rotate

* **A leak**, confirmed or suspected. Don't wait to be sure.
* **Routine hygiene**, on whatever schedule your security policy sets.
* **Staff or system turnover**, when whoever held the secret should no longer have it.

## Rotate

Trigger a rotation from the portal, or call the API:

```
POST /api/v1/agents/{id}/rotate-secret
```

You receive a new secret, **once**. Crucially, the previous secret stays valid for a short grace window. That window is what lets you roll the new value out without dropping in-flight calls — there's no instant where neither secret works.

## Swap it in

Replace the value wherever the agent reads it:

```env theme={null}
MUDRAID_SECRET=muid_sk_<new value>
```

Restart (or redeploy) the agent so it picks up the new secret. Once every instance is on the new value and the grace window closes, the old secret is dead.

## If you can't rotate in time

If the agent is outside your control, or the exposure is serious enough that you want it off *now*, revoke it instead of rotating — set its status to `revoked`:

```http theme={null}
PATCH /api/v1/agents/{id}/status
Content-Type: application/json

{ "status": "revoked" }
```

A revoked agent gets no new tokens immediately. Any token already issued stops working when it expires — within minutes, given the short token lifetime. Revocation is the hard stop; rotation is the graceful swap.

## What to expect

* **No outage** during a normal rotation — the grace window covers the overlap.
* **Tokens already minted** under the old secret keep working until they expire; they're signed by MudraID, not tied to the secret directly.
* **Revocation is faster and harsher** than rotation — use it when you need containment over continuity.

## Related

* [Agent identity](/guides/concepts/agent-identity)
* [Register and manage an agent](/guides/agent-developer/register-agent)
* [Trust & security](/security/overview)