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

# FastAPI Middleware

> Verify agents and enforce scopes on every route, before your handlers run.

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

```python theme={null}
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](/sdks/python-sdk/overview) 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

```bash theme={null}
pip install mudraid-middleware
```

Requires Python 3.10 or newer. It brings in `pyjwt[crypto]`, `cryptography`, `httpx`, `pyyaml`, and `starlette`.

<Note>
  During the v0.1 alpha the package isn't on PyPI yet. From the repo root: `pip install -e sdks/mudraid-middleware-python`.
</Note>

## 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 type     |    p50 |     p99 | Added vs bare app (p50) |
| -------------- | -----: | ------: | ----------------------: |
| `public: true` | 527 µs |  811 µs |                 +130 µs |
| Scope-gated    | 722 µs | 1403 µ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

* [Configuration](/sdks/middleware/configuration) — settings & defaults.
* [Error responses](/sdks/middleware/error-responses) — the stable error\_code contract.
* [Operator playbook](/sdks/middleware/operator-playbook) — running it day to day.
* [Quickstart](/guides/get-started/quickstart-platform) — a guided first integration.