Skip to main content
mudraid-middleware is how a platform protects its API. It’s middleware for FastAPI and Starlette: you add it once, point it at your mudraid_scopes.yaml, and every request is checked for a valid token and the right scope before it reaches your handlers. No decorators. No per-route auth code. No changes to your existing route files. 
from fastapi import FastAPI
from mudraid_middleware import MudraIDMiddleware

app = FastAPI()
app.add_middleware(MudraIDMiddleware)

@app.get("/api/v1/items")
def list_items():
    return {"items": [...]}   # runs only after the token and scope checks pass
Two lines plus a YAML file in your project root.

​
When to use it

Use the middleware on the platform side — in the API that agents call. If you’re building the agent that makes calls, you want the Python Agent SDK instead.

​
What it does per request

  1. Matches the method and path against the rules in mudraid_scopes.yaml.
  2. Lets public routes through untouched.
  3. Returns 404 for skip routes and routes with no rule — they’re invisible to agents.
  4. Reads the Authorization: Bearer token.
  5. Verifies the token’s signature, issuer, audience, and timing against MudraID’s published keys — locally, with no per-request callback. Keys are cached and refreshed automatically when MudraID rotates them.
  6. Checks the route’s required scope is present in the token.
  7. Forwards to your handler, or returns a structured {"error_code", "message"} error.
Your handlers only ever run for requests that are authenticated and in scope.

​
Install

pip install mudraid-middleware
Requires Python 3.10 or newer. It brings in pyjwt[crypto], cryptography, httpx, pyyaml, and starlette.
During the v0.1 alpha the package isn’t on PyPI yet. From the repo root: pip install -e sdks/mudraid-middleware-python.

​
Performance

The middleware verifies tokens locally, so the steady-state cost is small. Measured overhead over a bare FastAPI handler with a warm key cache:
Route typep50p99Added vs bare app (p50)
public: true527 µs811 µs+130 µs
Scope-gated722 µs1403 µs+310 µs
The scope-gated cost is dominated by the one-time signature verification per request. Fetching MudraID’s keys happens once at startup (and on rotation), not on every call.

​
Next