# AgentOS Middleware (/agent-os/middleware/overview)
v2.1.0
AgentOS is built on FastAPI, so you can add any [FastAPI/Starlette-compatible middleware](https://fastapi.tiangolo.com/tutorial/middleware/) for authentication, logging, monitoring, and security.
Agno ships with a built-in auth middleware (`AuthMiddleware`) that handles JWTs, service-account tokens, and the OS security key. You can write your own custom middleware for rate limiting, request logging, and security headers.
See the following guides:
Create your own middleware for logging, rate limiting, monitoring, and security.
Built-in JWT authentication with automatic parameter injection and claims extraction.
JWT validation with role-based access control and fine-grained permission scopes.
## Quick Start [#quick-start]
This local example uses HS256 with a secret you supply. Install the dependencies, set the server keys, and start [PostgreSQL](/database/providers/postgres/usage/postgres-for-agent) on port 5532 with the shown credentials (or change `db_url`):
```bash
uv pip install -U "agno[os]" openai "psycopg[binary]"
export OPENAI_API_KEY="your_openai_api_key"
export JWT_VERIFICATION_KEY="replace-with-a-long-random-local-secret"
```
Save the code as `agent_os.py` and run `python agent_os.py`. It adds middleware to the FastAPI app returned by `get_app()`:
```python title="agent_os.py"
import os
from agno.os import AgentOS
from agno.os.middleware.jwt import AuthMiddleware
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.agent import Agent
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
agent = Agent(
name="Basic Agent",
model=OpenAIResponses(id="gpt-5.2"),
db=db,
)
# Create your AgentOS app
agent_os = AgentOS(id="middleware-demo", agents=[agent])
app = agent_os.get_app()
# Add middleware
app.add_middleware(
AuthMiddleware,
verification_keys=[os.environ["JWT_VERIFICATION_KEY"]],
algorithm="HS256",
verify_audience=True,
validate=True
)
if __name__ == "__main__":
agent_os.serve(app="agent_os:app", reload=True)
```
In a second terminal with the same environment and secret, create a short-lived local token and request the configuration:
```python
import os
import time
import httpx
import jwt
token = jwt.encode(
{"sub": "demo-user", "aud": "middleware-demo", "exp": int(time.time()) + 300},
os.environ["JWT_VERIFICATION_KEY"],
algorithm="HS256",
)
response = httpx.get(
"http://localhost:7777/config",
headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())
```
Later middleware patterns assume their application-specific classes and callbacks are defined.
Test middleware thoroughly in your own staging environment before production deployment.
**Performance Impact:** Each middleware layer adds latency to requests.
## Common Use Cases [#common-use-cases]
**Secure your AgentOS with JWT authentication:**
* Extract tokens from headers or cookies
* Automatic parameter injection (user\_id, session\_id)
* Custom claims extraction for `dependencies` and `session_state`
* Route exclusion for public endpoints
[Learn more about JWT Middleware](/agent-os/middleware/jwt)
**Control access with permission scopes:**
* Validate JWT scopes against required permissions
* Per-resource access control (specific agents/teams/workflows)
* Admin scope for full access
* Customizable scope mappings
[Authorization](/agent-os/security/authorization/overview)
**Prevent API abuse with rate limiting:**
```python
class RateLimitMiddleware(BaseHTTPMiddleware):
def __init__(self, app, requests_per_minute: int = 60):
super().__init__(app)
self.requests_per_minute = requests_per_minute
# ... implementation
app.add_middleware(RateLimitMiddleware, requests_per_minute=100)
```
**Monitor requests and responses:**
```python
class LoggingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
start_time = time.time()
response = await call_next(request)
process_time = time.time() - start_time
# Log request details...
return response
```
See [Custom Middleware](/agent-os/usage/middleware/custom-middleware) for complete rate-limiting and request-logging implementations.
## Middleware Execution Order [#middleware-execution-order]
Middleware is executed in reverse order of addition. The last middleware added runs first.
```python
app.add_middleware(MiddlewareA) # Runs third (closest to route)
app.add_middleware(MiddlewareB) # Runs second
app.add_middleware(MiddlewareC) # Runs first (outermost)
# Request: C -> B -> A -> Your Route
# Response: Your Route -> A -> B -> C
```
**Best Practice:** Aim for this execution order. Since the last middleware added runs first, add them in reverse:
1. **Security middleware** (CORS, security headers)
2. **Authentication middleware** (JWT, session validation)
3. **Monitoring middleware** (logging, metrics)
4. **Business logic middleware** (rate limiting, custom logic)
## Developer Resources [#developer-resources]
### Examples [#examples]
JWT authentication using Authorization headers for API clients.
JWT authentication using HTTP-only cookies for web applications.
Rate limiting and request logging middleware implementation.
Custom FastAPI app with JWT middleware and AgentOS integration.
Scopes, roles, and access control.
### External Resources [#external-resources]
Official FastAPI middleware documentation and examples.
Starlette middleware reference and implementation guides.