Skip to main content

​
V1: route and scope enforcement

Set the issuer and the audience for OAuth access tokens. Agents’ access tokens carry your environment’s authorization-server issuer as iss (the issuer at /.well-known/oauth-authorization-server) and your platform’s canonical resource URI as aud. The defaults above match the claims of retired native agent tokens, so with them every agent call fails with WRONG_ISSUER or WRONG_AUDIENCE. The middleware compares the audience exactly; it never infers one from the presented token, and does not accept the platform ID as a second audience once expected_audience is set. Keep the real platform_id in your YAML either way. MUDRAID_EXPECTED_ISSUERS is comma-separated: set one value to pin a single issuer, or list several to accept any of them during an issuer migration. A token whose iss isn’t in the accepted set is rejected with WRONG_ISSUER.
MUDRAID_JWKS_URL is required — there is no default. The middleware raises at construction if it is unset, rather than starting and then rejecting every token.That is deliberate. A JWKS URL tells the middleware where to fetch the signing keys it validates tokens against, so a compiled-in default would mean an unconfigured platform fetching its trust anchors from a host nobody chose. It would also make the package environment-specific, and the same build has to run against every MudraID environment.Point it at the /.well-known/jwks.json path on the environment your platform is registered with — the MudraID portal prints it on the credential screen. It must be https; http is accepted only to a loopback host with the local-development opt-in, and anything else raises MudraIDInsecureJwksUrlError at construction.
Everything else (cache TTLs, clock-skew leeway, body limits) is internal and stable.

​
The YAML path

By default the middleware looks for mudraid_scopes.yaml in the working directory. Set scopes_yaml_path if it lives elsewhere. The file is loaded once, on the first request. To change it, redeploy. See Manage the scopes lifecycle.

​
V2 mode

Select it with mode="v2" and a v2_config=. V2 makes no use of the YAML, JWKS, issuer or audience settings above — the token is verified by MudraID’s /decide. Set protected_paths to your MCP Streamable HTTP endpoints, such as ("/mcp",). Leaving it None applies MCP framing rules to every route on the app. Prefixes match whole path segments, every spelling of the request path is tested, and a prefix with dot segments, percent-escapes or a query string raises ValueError at construction. When surface_platform_id / surface_environment are set, a bundle activates only if MudraID attributes your adapter token to that platform and the signed bundle claims it; anything else is refused and reported on the adapter row in the portal. The adapter token must differ between environments. You never configure a bundle-signing secret: bundle signatures are verified with public keys the client fetches itself.