mudraid_scopes.yaml isn’t static — you’ll add routes and adjust permissions over time. This guide explains how the middleware loads the file and how to roll out changes without surprises.
How the file is loaded
The middleware readsmudraid_scopes.yaml once, on the first request, and holds the parsed result in memory for the life of the process. It does not re-read the file per request, and it does not hot-reload.
That means a change on disk has no effect until the process restarts.
Changing scopes
- Update the scopes in the MudraID portal.
- Re-export
mudraid_scopes.yaml. - Put the new file in place.
- Redeploy or restart your service.
Hot-reload is intentionally left out. Reloading auth rules under live traffic is a subtle, error-prone thing to get right. Tying changes to a restart keeps the running middleware’s behavior a known quantity — what’s in memory is exactly what was on disk at boot.
Rolling out without downtime
Because changes apply at restart, use your normal zero-downtime deploy to roll them out: bring up new instances with the new file, drain the old ones. During the overlap, some instances enforce the old rules and some the new — so make changes additive where you can (add a scope before requiring it on a route) to avoid a window where valid agents are briefly rejected.Keep the portal as the source of truth
Don’t hand-edit the YAML in production. The portal generates it, and the next export will overwrite local edits — so any by-hand change silently disappears on the next sync, and your running rules drift from what the portal thinks is true. Editing by hand for local testing is fine; just don’t let it become the system of record.When the file is broken
If the YAML is missing or malformed, the middleware returns500 MIDDLEWARE_NOT_READY and logs the parse error.
The failure is not cached: fix the file and the very next request succeeds, no restart required for that recovery. (Successful loads, by contrast, are held in memory — so a valid change still needs a restart.)