AgentOS provides built-in JWT middleware for authentication, parameter injection, and automatic claims extraction. This middleware can extract JWT tokens from Authorization headers or cookies and automatically inject values into the AgentOS endpoints.

​
Quick Start

The JWT middleware provides two main features:
  1. Token Validation: Validates JWT tokens and handles authentication
  2. Parameter Injection: Automatically injects user_id, session_id, and custom claims into endpoint parameters
from agno.os.middleware import JWTMiddleware
from agno.os.middleware.jwt import TokenSource

app.add_middleware(
    JWTMiddleware,
    secret_key="your-jwt-secret-key", # or use JWT_SECRET_KEY environment variable
    algorithm="HS256",
    user_id_claim="sub",  # Extract user_id from 'sub' claim
    session_id_claim="session_id",  # Extract session_id from claim
    dependencies_claims=["name", "email", "roles"],  # Additional claims
    validate=True,  # Enable token validation
)

​
Configuration Options

ParameterDescriptionDefault
secret_keySecret key for JWT verificationOptional, will use JWT_SECRET_KEY environment variable if not provided
algorithmJWT algorithm (HS256, RS256, etc.)”HS256”
token_sourceWhere to extract token from. HEADER, COOKIE, or BOTH.TokenSource.HEADER
token_header_keyKey to use for the Authorization header (only used when token_source is HEADER or BOTH)“Authorization”
cookie_nameCookie name when using cookies (only used when token_source is COOKIE or BOTH)“access_token”
validateEnable token validationTrue
excluded_route_pathsRoutes to skip middleware (useful for health checks, etc.)[]
scopes_claimJWT claim for scopesNone
user_id_claimJWT claim for user ID”sub”
session_id_claimJWT claim for session ID”session_id”
dependencies_claimsList of additional claims to extract for dependencies parameter[]
session_state_claimsList of additional claims to extract for session_state parameter[]

​
Token Sources

The middleware supports three token sources:
Extract JWT from Authorization: Bearer <token> header.
from agno.os.middleware.jwt import TokenSource

app.add_middleware(
    JWTMiddleware,
    secret_key="your-secret",
    token_source=TokenSource.HEADER,  # Default
    
)

​
Parameter Injection

The middleware automatically injects JWT claims into the request object flowing across your FastAPI state. This is a great way to resolve data from your token into parameters received by your endpoints. These are the parameters automatically injected by our JWT middleware into your endpoints:
  • user_id
  • session_id
  • dependencies
  • session_state For example, in /agents/{agent_id}/runs, the user_id, session_id, dependencies and session_state are automatically used if they were extracted from the JWT token.
This is useful for:
  • Automatically using the user_id and session_id from your JWT token when running an agent
  • Automatically filtering sessions retrieved from /sessions endpoints by user_id (where applicable)
  • Automatically injecting dependencies from claims in your JWT token into the agent run, which then is available on tools called by your agent
See the full example for more details.

​
Security Features

Remember to always use strong secret keys, don’t hardcode them anywhere in your code and enable validation in production.
Token Validation: When validate=True, the middleware:
  • Verifies JWT signature using the secret key
  • Checks token expiration (exp claim)
  • Returns 401 errors for invalid/expired tokens
HTTP-Only Cookies: When using cookies:
  • Set httponly=True to prevent JavaScript access (XSS protection)
  • Set secure=True for HTTPS-only transmission
  • Set samesite="strict" for CSRF protection

​
Excluded Routes

Skip middleware for specific routes: 
app.add_middleware(
    JWTMiddleware,
    secret_key="your-secret",
    excluded_route_paths=[
        "/health",
        "/auth/login", 
        "/auth/register",
        "/public/*",  # Wildcards supported
    ]
)

​
Developer Resources