JWT Middleware

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 three main features:

Token Validation: Validates JWT tokens and handles authentication
Parameter Injection: Automatically injects user_id, session_id, and custom claims into endpoint parameters
RBAC Authorization: Validates scopes against required permissions for each endpoint

jwt_middleware_setup.py

from agno.os.middleware import JWTMiddleware
from agno.os.middleware.jwt import TokenSource

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-jwt-verification-key"],  # or use JWT_VERIFICATION_KEY environment variable
    algorithm="RS256",  # RS256 for asymmetric keys, HS256 for symmetric
    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
    authorization=True,  # Enable RBAC scope checking
    verify_audience=True,  # Verify `aud` claim matches AgentOS ID
)

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,
    verification_keys=["your-key"],
    token_source=TokenSource.HEADER,  # Default
)

Extract JWT from HTTP-only cookies for web applications.

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-key"],
    token_source=TokenSource.COOKIE,
    cookie_name="access_token",  # Default
)

Try both header and cookie (header takes precedence).

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-key"],
    token_source=TokenSource.BOTH,
    cookie_name="access_token",  # Default
    token_header_key="Authorization",  # Default
)

JWKS File Support

For environments using RSA keys managed via JWKS (JSON Web Key Set), you can point to a static JWKS file instead of providing raw public keys:

jwks_file_setup.py

app.add_middleware(
    JWTMiddleware,
    jwks_file="/path/to/jwks.json",
    algorithm="RS256",
    authorization=True,
)

The middleware will:

Load public keys from the JWKS file at startup
Match incoming tokens by their kid (key ID) header claim
Validate signatures using the appropriate key

JWKS File Format

The JWKS file should follow the standard format:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "my-key-id",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGc...",
      "e": "AQAB"
    }
  ]
}

Environment Variable

You can also set the JWKS file path via environment variable:

export JWT_JWKS_FILE="/path/to/jwks.json"

JWKS keys are tried first (matched by kid). If no matching key is found, the middleware falls back to verification_keys if provided.

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 verification keys, store them securely (not in code), and enable validation in production.

Token Validation: When validate=True, the middleware:

Verifies JWT signature using the verification key
Checks token expiration (exp claim)
Returns 401 errors for invalid/expired tokens

Audience Verification: When verify_audience=True, the middleware:

If audience is provided, it will validate the token’s audience claim matches the expected audience claim
If audience is not provided, it will validate the token’s audience claim matches the AgentOS ID
Optionally set the audience_claim to validate a custom audience claim
Returns 401 for tokens with mismatched audience

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

RBAC Authorization

Enable Role-Based Access Control (RBAC) to validate JWT scopes against required permissions:

jwt_with_rbac.py

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-jwt-key"],
    algorithm="RS256",
    authorization=True,  # Enable RBAC
    verify_audience=True,  # Verify aud matches AgentOS ID
)

When authorization=True, the middleware:

Checks the scopes claim in JWT tokens
Validates scopes against required permissions for each endpoint
Returns 403 Forbidden for insufficient permissions

Scope Format

Format	Example	Description
`resource:action`	`agents:read`	Access all resources
`resource:<id>:action`	`agents:my-agent:run`	Access specific resource
`resource:*:action`	`agents:*:run`	Wildcard access
`agent_os:admin`	`agent_os:admin`	Full admin access

Custom Scope Mappings

Override or extend default scope mappings:

custom_scope_mappings.py

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-key"],
    authorization=True,
    scope_mappings={
        # Override default
        "GET /agents": ["custom:agents:list"],
        # Add new endpoint
        "POST /custom/action": ["custom:write"],
        # Allow without scopes
        "GET /public": [],
    }
)

For detailed RBAC documentation including all available scopes and default mappings, see RBAC Documentation.

Excluded Routes

Skip middleware for specific routes:

jwt_excluded_routes.py

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-key"],
    excluded_route_paths=[
        "/health",
        "/auth/login", 
        "/auth/register",
        "/public/*",  # Wildcards supported
    ]
)

Configuration Options

See the JWTMiddleware Reference for the complete list of configuration options.

Authentication Options

Parameter	Description	Default
`verification_keys`	List of keys for JWT verification. For RS256, use public keys. For HS256, use shared secrets. Each key is tried in order until one succeeds.	`JWT_VERIFICATION_KEY` env var
`jwks_file`	Path to a static JWKS file containing public keys. Keys are matched by `kid` from the JWT header.	`JWT_JWKS_FILE` env var
`secret_key`	(Deprecated) Use `verification_keys` instead.	-
`algorithm`	JWT algorithm (RS256, HS256, ES256, etc.)	`"RS256"`
`validate`	Enable token validation	`True`

Token Source Options

Parameter	Description	Default
`token_source`	Where to extract token from: `HEADER`, `COOKIE`, or `BOTH`	`TokenSource.HEADER`
`token_header_key`	Header key for Authorization (when using HEADER or BOTH)	`"Authorization"`
`cookie_name`	Cookie name (when using COOKIE or BOTH)	`"access_token"`

Claim Extraction Options

Parameter	Description	Default
`user_id_claim`	JWT claim for user ID	`"sub"`
`session_id_claim`	JWT claim for session ID	`"session_id"`
`scopes_claim`	JWT claim for scopes	`"scopes"`
`audience_claim`	JWT claim for audience/OS ID	`"aud"`
`dependencies_claims`	List of claims to extract for `dependencies` parameter	`[]`
`session_state_claims`	List of claims to extract for `session_state` parameter	`[]`

Authorization Options (RBAC)

Parameter	Description	Default
`authorization`	Enable RBAC scope checking	`False`
`verify_audience`	Verify `aud` claim matches AgentOS ID	`False`
`audience`	Expected audience claim to validate against the token’s audience claim	`AgentOS ID`
`scope_mappings`	Custom route-to-scope mappings (additive to defaults)	`None`
`admin_scope`	Scope that grants full admin access	`"agent_os:admin"`
`excluded_route_paths`	Routes to skip JWT/RBAC checks	See below

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.

RBAC Documentation

Detailed RBAC scopes, permissions, and access control configuration.

JWTMiddleware Reference

Complete JWT middleware class reference.

External Resources

PyJWT Documentation

Official PyJWT library documentation for JWT encoding and decoding.

Get Started

AgentOS

Usage

JWT Middleware

Token Sources

JWKS File Support

JWKS File Format

Environment Variable

Parameter Injection

Security Features

RBAC Authorization

Scope Format

Custom Scope Mappings

Excluded Routes

Configuration Options

Authentication Options

Token Source Options

Claim Extraction Options

Authorization Options (RBAC)

Examples

JWT with Headers

JWT with Cookies

Custom FastAPI + JWT

RBAC Documentation

JWTMiddleware Reference

External Resources

PyJWT Documentation

Get Started

AgentOS

Usage

​Token Sources

​JWKS File Support

​JWKS File Format

​Environment Variable

​Parameter Injection

​Security Features

​RBAC Authorization

​Scope Format

​Custom Scope Mappings

​Excluded Routes

​Configuration Options

​Authentication Options

​Token Source Options

​Claim Extraction Options

​Authorization Options (RBAC)

​Examples

JWT with Headers

JWT with Cookies

Custom FastAPI + JWT

RBAC Documentation

JWTMiddleware Reference

​External Resources

PyJWT Documentation

Token Sources

JWKS File Support

JWKS File Format

Environment Variable

Parameter Injection

Security Features

RBAC Authorization

Scope Format

Custom Scope Mappings

Excluded Routes

Configuration Options

Authentication Options

Token Source Options

Claim Extraction Options

Authorization Options (RBAC)

Examples

External Resources