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

# Operator playbook

> Running the middleware day to day.

The common operational situations and what the middleware does.

## Updating scopes or routes

The middleware loads `mudraid_scopes.yaml` once, on the first request, and holds it in memory.

To pick up changes: redeploy, or restart the process. There is no hot-reload in v1. The single-source-of-truth contract is easier to reason about with a restart in the middle.

## MudraID key rotation

When MudraID rotates its signing key, the middleware:

1. Receives a token signed under a new `kid`.
2. Looks up the `kid` in its cached JWKS. Not found.
3. Refetches the JWKS. One in-flight refresh under contention.
4. Verifies against the new key. Success.

Zero operator action. Covered by integration tests.

## JWKS endpoint unreachable

Affected requests get `500 JWKS_UNAVAILABLE`, logged at WARNING.

The cache is not invalidated on a failed fetch. A transient blip doesn't take down every cached key.

## Misconfigured YAML

The middleware loads the YAML lazily on the first request. A schema error returns `500 MIDDLEWARE_NOT_READY`, logged at ERROR.

The failure is not cached. Fix the YAML and the next request succeeds. No restart needed for that case.

## Diagnostics

```python theme={null}
import logging
logging.getLogger("mudraid_middleware").setLevel(logging.INFO)
```

Bootstrap, JWKS fetches, retries, and 500-level events surface at INFO and WARNING.

## Related

* [Manage the scopes lifecycle](/guides/platform-operator/scopes-lifecycle)
* [Survive key rotation](/guides/platform-operator/key-rotation)
* [Error responses](/sdks/middleware/error-responses)