Security & Auth

AgentOS security works in layers: JWT authentication at the edge, scope-based authorization per endpoint, per-request component copies, and opt-in per-user data isolation. Network controls and database permissions cover the rest.

Network-layer controls (rate limiting, WAF, IP allowlists, mTLS) live at your reverse proxy or API gateway layer.

Authentication

A production AgentOS sits behind JWT-validating middleware. Tokens can come from the AgentOS control plane, your own backend, or a third-party identity provider. Your service verifies them with the matching public key. See Self-Hosted for BYO and third-party setup.

from agno.os import AgentOS

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,  # reads JWT_VERIFICATION_KEY from env
)

authorization=True drives both layers:

Authentication (this section): requires a valid JWT on protected central routes.
Authorization (below): enforces the token’s scopes per endpoint.

A small set of public routes are exempt from the JWT requirement: /, /health, /info, /docs, /redoc, /openapi.json, /docs/oauth2-redirect. Slack, Telegram, and WhatsApp routes use their interface-specific request verification instead of central JWT middleware.

Generate a Verification Key from the Control Plane

Toggle JWT authorization

Open os.agno.com → Add OS → Live → paste your URL. Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.

Copy the public key

Copy the public key for your AgentOS from the modal.

Set the verification key

Set the JWT_VERIFICATION_KEY environment variable to your public key in your .env file or export it directly in your terminal:

export JWT_VERIFICATION_KEY="your-public-key"

Or, if you manage keys via a JWKS file, point AgentOS at it instead:

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

When tokens are issued by the AgentOS control plane, it keeps the private key and your service only sees the public key. See Generate a Verification Key from the Control Plane for the full walkthrough.

Configure JWTs from Your Backend or IDP

If you’re issuing JWTs from your own backend, or from a third-party identity provider like WorkOS, Auth0, or Okta, pass an AuthorizationConfig:

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

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=["public-key-1", "public-key-2"],   # multi-issuer
        algorithm="RS256",
        verify_audience=True,
        audience="my-agent-os",   # must match the token's `aud`; defaults to the AgentOS id
        user_isolation=True,      # see below
    ),
)

verification_keys is a list. AgentOS tries each key in order until one verifies the token, so you can accept tokens from multiple issuers at the same time. For key rotation, use a JWKS file instead. With verify_audience=True, AgentOS rejects tokens whose aud claim doesn’t match the expected audience. That expected value defaults to the AgentOS id; set audience to override it when your provider mints a different value. JWT claim names (scopes, sub) are configured on the JWT middleware itself, not on AuthorizationConfig. The defaults (scopes for the scopes claim, sub for the user ID claim) match the tokens minted by the control plane. For the full self-hosted setup including multi-issuer, see Self-Hosted.

Authorization

AgentOS reads the caller’s permissions from a JWT claim (scopes by default). If your provider uses a different name, such as WorkOS’s permissions, set the scopes_claim argument on the JWT middleware. It is not a field on AuthorizationConfig. Endpoints are gated on those scopes.

Scope	Grants
`agents:read`	List agents and read their config
`agents:<id>:run`	Run a specific agent
`agents:*:run`	Run any agent (same pattern for teams, workflows)
`agent_os:admin`	Full access including session, memory, and trace queries

The AgentOS control plane mints each token with the appropriate scopes. Scopes are bundled into roles and assigned to users in the control plane: the AgentOS control plane provides three default roles (owner, admin, member), and custom roles are available on Enterprise. Self-hosters define roles in their identity provider or backend. See the scope reference for the full scope list, Default Roles for what each grants, and Custom Roles to compose your own.

Request isolation

Each run request gets a fresh copy of the agent, team, or workflow it’s hitting. AgentOS calls deep_copy() on the registered component before the run, so mutable per-run state (session-scoped variables, tool execution context, run metadata) never bleeds between concurrent calls. Heavy resources (the database connection, the model client, MCP tool handles) are shared by reference; only the mutable per-run state is isolated. You get cheap concurrency without two requests racing on the same in-memory agent instance. This is on by default for run endpoints. There’s nothing to configure.

User isolation

Per-user data isolation is opt-in. Authorization remains active without it, but user-scoped database reads are not automatically filtered by the JWT subject. A caller with session or memory read scopes can query rows across users unless another restriction applies. For multi-tenant deployments, turn it on:

from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=[public_key],
        user_isolation=True,   # requires authorization=True; the user_id comes from the JWT sub
    ),
)

With user_isolation=True, every non-admin caller gets:

Guarantee	How
No cross-user reads	The JWT `sub` is threaded as `user_id` on every user-scoped read (sessions, memory, traces). Callers only see their own rows.
No cross-user writes	`user_id` is coerced on every write, so a non-admin can’t persist a session, memory, or trace attributed to another user.
Run ownership	Cancel, resume, and continue routes require `session_id` and verify the run belongs to the caller’s session.
WebSocket reconnect	Reconnecting to a workflow run requires `session_id` and `workflow_id`, then verifies the caller owns the run.

Admin callers with the configured admin_scope, which defaults to agent_os:admin, bypass user isolation and receive the unscoped view. Per-user isolation requires a database that records user_id (PostgreSQL recommended for production).

Defaults

Concern	Default behavior
Authentication	`authorization=False`. Opt in with `authorization=True` and `JWT_VERIFICATION_KEY` for production.
Request isolation	On. Run endpoints deep-copy the registered component.
User isolation	Off. Opt in via `AuthorizationConfig(user_isolation=True)` for multi-tenant.

See the AuthorizationConfig reference for all configuration options and their defaults.

Welcome

Get Started

Features

Use Cases

Security & Auth

Authentication

Generate a Verification Key from the Control Plane

Configure JWTs from Your Backend or IDP

Authorization

Request isolation

User isolation

Defaults

​Authentication

​Generate a Verification Key from the Control Plane

​Configure JWTs from Your Backend or IDP

​Authorization

​Request isolation

​User isolation

​Defaults

Authentication

Generate a Verification Key from the Control Plane

Configure JWTs from Your Backend or IDP

Authorization

Request isolation

User isolation

Defaults