Auth Middleware

AuthMiddleware is the AgentOS authentication layer. It validates JWTs, service-account tokens (agno_pat_...), and the OS security key. For JWTs it extracts tokens from Authorization headers or cookies, validates them, and injects user_id, session_id, and custom claims into your endpoints. This page covers the JWT configuration. For the other two credential types, see Service Accounts and the security key.

The middleware provides three 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
3. RBAC Authorization: Validates scopes against required permissions for each endpoint

The examples on this page are alternative middleware configuration fragments. Create app = agent_os.get_app() first, as in the middleware quickstart, and add your chosen middleware before serving. Replace verification-key placeholders with a real key for the selected algorithm; the quickstart includes local token generation. Do not stack the alternatives together.

from agno.os.middleware.jwt import AuthMiddleware

app.add_middleware(
    AuthMiddleware,
    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
)

Coverage Across Surfaces

JWT and OS security-key deployments share the parent-app authentication layer across the runtime surfaces below. An MCP OAuth configuration uses its configured OAuth authentication path; see MCP security. Route scopes still determine which operations a credential can call.

Credential Dispatch

The middleware resolves each bearer credential in order:

1. Tokens with the agno_pat_ prefix authenticate as service accounts against the AgentOS database. This happens before JWT validation. Service-account scopes are enforced even when authorization=False, since they are ACL data owned by your AgentOS instance.
2. The internal service token, used by the scheduler executor to run scheduled jobs.
3. The OS security key, when no JWT source is configured.
4. Anything else is validated as a JWT.

Token Sources

The middleware supports three token sources:

from agno.os.middleware.jwt import AuthMiddleware, TokenSource

app.add_middleware(
    AuthMiddleware,
    verification_keys=["your-key"],
    token_source=TokenSource.HEADER,  # Default
)

from agno.os.middleware.jwt import AuthMiddleware, TokenSource

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

from agno.os.middleware.jwt import AuthMiddleware, TokenSource

app.add_middleware(
    AuthMiddleware,
    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:

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

The middleware will:

1. Load public keys from the JWKS file at startup
2. Match incoming tokens by their kid (key ID) header claim
3. 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"

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

See the full example.

Security Features

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

Local Development

Skip signature verification in local development, or when an upstream API gateway already validates JWTs.

from agno.os.middleware.jwt import AuthMiddleware

app.add_middleware(
    AuthMiddleware,
    validate=False,
)

No verification key is required. Claims are extracted from the token but not authenticated.

RBAC Authorization

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

app.add_middleware(
    AuthMiddleware,
    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

Custom Scope Mappings

Override or extend default scope mappings:

app.add_middleware(
    AuthMiddleware,
    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": [],
    }
)

User Isolation

RBAC controls which endpoints a caller can hit. User isolation controls which rows they can see and mutate. The two are independent toggles.

app.add_middleware(
    AuthMiddleware,
    verification_keys=["your-jwt-key"],
    authorization=True,
    user_isolation=True,
)

When user_isolation=True, non-admin callers are scoped to the user_id from the JWT sub claim across sessions, memories, traces, approvals, and other user-owned AgentOS resources. Callers holding admin_scope bypass isolation. See Per-User Data Isolation for the full behavior.

Excluded Routes

These routes skip JWT and RBAC checks by default:

["/", "/health", "/info", "/docs", "/redoc", "/openapi.json", "/docs/oauth2-redirect"]

Override them with excluded_route_paths:

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

Configuration Options

See the AuthMiddleware reference for the complete list of configuration options.

Authentication Options

Token Source Options

Claim Extraction Options

Authorization Options (RBAC)

Examples

External Resources