> ## 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.

# Manage the scopes lifecycle

> How the scopes file loads, how to change it safely, and how failures recover.

Your `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 reads `mudraid_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

1. Update the scopes in the MudraID portal.
2. Re-export `mudraid_scopes.yaml`.
3. Put the new file in place.
4. **Redeploy or restart** your service.

The restart is the moment the change takes effect.

<Note>
  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.
</Note>

## 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 returns `500 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.)

## Related

* [Define scopes](/guides/platform-operator/define-scopes)
* [Operator playbook](/sdks/middleware/operator-playbook)
* [Interpret verification error codes](/guides/platform-operator/error-codes)