Skip to main content
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: 
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: 
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.