AuthorizationConfig

Configuration for JWT verification when RBAC authorization is enabled on AgentOS.

Import

from agno.os.config import AuthorizationConfig

Asymmetric algorithm prerequisite

The agno[os] extra installs base PyJWT. Add PyJWT's optional cryptography dependencies for RS* and ES* algorithms:

uv pip install "PyJWT[crypto]"

Parameters

Parameter	Type	Default	Description
`verification_keys`	`Optional[List[str]]`	`None`	List of keys used to verify JWT signatures. For asymmetric algorithms (e.g. RS256), use public keys. For symmetric algorithms (e.g. HS256), use shared secrets. Each key is tried in order until one succeeds. Useful for accepting tokens from multiple issuers.
`jwks_file`	`Optional[str]`	`None`	Path to a static JWKS (JSON Web Key Set) file containing public keys. Keys are matched by `kid` (key ID) from the JWT header. Alternative to `verification_keys` for RSA key management.
`algorithm`	`Optional[str]`	`None` (`"RS256"` when unset)	JWT algorithm for token verification. Common options: `RS256` (asymmetric), `HS256` (symmetric).
`verify_audience`	`Optional[bool]`	`None` (treated as `False`)	Whether to verify the JWT's `aud` claim matches the expected audience.
`audience`	`Optional[str]`	`None` (AgentOS `id` when checked)	Expected audience claim. When `verify_audience=True`, the token's `aud` must match this value. Defaults to the AgentOS `id`.
`admin_scope`	`Optional[str]`	`None` (`"agent_os:admin"` when unset)	The scope that grants full admin access. Holders bypass user isolation and can access all data.
`excluded_route_paths`	`Optional[List[str]]`	`None`	Additional `fnmatch` route patterns that bypass all AgentOS authentication. Merged with the runtime's default public, interface, and provider discovery exclusions.
`user_isolation`	`bool`	`False`	Opt-in per-user isolation for user-owned data and resources throughout AgentOS. When `True`, non-admin callers can only access data and resources associated with their JWT `sub` claim.

When user_isolation=True, every non-admin JWT must include a non-empty string sub claim. Configure the token issuer or an authentication layer to reject tokens without this claim before they reach AgentOS. A token without a usable sub can pass JWT verification, but AgentOS cannot apply per-user filtering or ownership enforcement to that caller.

Usage

from agno.os import AgentOS
from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=["your-public-key-or-secret"],
        algorithm="RS256",
    ),
)

Algorithm Options

Algorithm	Type	Key Format
`RS256`	Asymmetric (RSA)	Public key (PEM format)
`RS384`	Asymmetric (RSA)	Public key (PEM format)
`RS512`	Asymmetric (RSA)	Public key (PEM format)
`HS256`	Symmetric (HMAC)	Shared secret string
`HS384`	Symmetric (HMAC)	Shared secret string
`HS512`	Symmetric (HMAC)	Shared secret string
`ES256`	Asymmetric (ECDSA)	Public key (PEM format)
`ES384`	Asymmetric (ECDSA)	Public key (PEM format)
`ES512`	Asymmetric (ECDSA)	Public key (PEM format)

Examples

Using RS256 (Asymmetric)

# RS256 with a public key
authorization_config = AuthorizationConfig(
    verification_keys=["""-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----"""],
    algorithm="RS256",
)

Using HS256 (Symmetric)

# HS256 with a shared secret
authorization_config = AuthorizationConfig(
    verification_keys=["your-256-bit-secret-key"],
    algorithm="HS256",
)

Using JWKS File

# RS256 with a JWKS file
authorization_config = AuthorizationConfig(
    jwks_file="/path/to/jwks.json",
    algorithm="RS256",
)

The JWKS file should follow the standard format:

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