Skip to main content
Authenticate and authorize requests to your AgentOS application using JWT tokens. The middleware extracts tokens from Authorization headers or cookies, validates them, and automatically injects user_id, session_id, and custom claims into your endpoints. 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
jwt_middleware_setup.py
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
)

​
Token Sources

The middleware supports three token sources:
  • Authorization Header
  • HTTP-Only Cookies
  • Both 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 AgentOS endpoints. The following parameters are extracted from tokens and injected into requests:
  • user_id - User identifier from token claims
  • session_id - Session identifier from token claims
  • dependencies - Custom claims for agent tools
  • session_state - Custom claims for session management
For example, the /agents/{agent_id}/runs endpoint automatically uses user_id, session_id, dependencies, and session_state from the JWT token when available. 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
View the full example for more details.

​
Security Features

Use strong secret keys, store them securely (not in 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:
jwt_excluded_routes.py
app.add_middleware(
    JWTMiddleware,
    secret_key="your-secret",
    excluded_route_paths=[
        "/health",
        "/auth/login", 
        "/auth/register",
        "/public/*",  # Wildcards supported
    ]
)

​
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.)None
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[]

​
Examples

JWT with Headers

JWT authentication using Authorization headers for API clients.

JWT with Cookies

JWT authentication using HTTP-only cookies for web applications.

Custom FastAPI + JWT

Custom FastAPI app with JWT middleware and AgentOS integration.

​
External Resources

PyJWT Documentation

Official PyJWT library documentation for JWT encoding and decoding.