Skip to main content
MudraID rotates the keys it signs tokens with from time to time — normal security hygiene. The headline for platform operators: you don’t have to do anything. The middleware handles rotation on its own. This guide explains why, so a rotation doesn’t look like an incident.

​
What happens during a rotation

  1. A token arrives signed under a key the middleware hasn’t seen (a new key id).
  2. The middleware looks it up in its cached set of MudraID keys — not found.
  3. It fetches the latest keys from MudraID. Under load, it does this once, not once per request.
  4. It finds the new key, verifies the token, and serves the request.
No restart. No config change. No redeploy. The first token under a new key triggers the refresh, and everything after it is served from the updated cache.

​
The cache, briefly

The middleware caches MudraID’s public keys and reuses them so verification stays local and fast. The reactive refresh on an unknown key is what makes rotation seamless — you don’t wait for a cache timer to notice the new key.

​
If MudraID’s keys are briefly unreachable

If the middleware needs to fetch keys and can’t reach MudraID, the affected requests return 500 JWKS_UNAVAILABLE and a warning is logged. The existing cache is not thrown away on a failed fetch, so a brief network blip doesn’t invalidate keys you already hold — only requests that genuinely need a not-yet-cached key are affected.

​
What to watch (optional)

  • A spike in JWKS_UNAVAILABLE means your network path to MudraID is having trouble — not that anything is misconfigured.
  • A brief blip of INVALID_TOKEN right at a rotation is normal and self-corrects as the refresh lands. A sustained one is worth a look.
In short: rotation is a non-event for you. It’s worth knowing the mechanism only so it doesn’t get mistaken for a problem.