Role-Based Access Control (RBAC)

AgentOS provides built-in Role-Based Access Control (RBAC) that validates JWT scopes against required permissions for each endpoint of the API. This allows you to control who can access and run your agents, teams, and workflows, as well as other functions on the AgentOS API. This functionality enables you to control access when building your own applications on AgentOS. Visualize how identity and authorization flow in AgentOS RBAC:

The Control Plane (or your auth system) generates signed JWT tokens which encode user identity and permissions.
JWT tokens are presented on every API call from your application’s backend, UI, or integrations.
AgentOS validates each JWT and checks for the required scopes before granting access to agents, teams, or workflows, and other internal resources.

Quick Start

Enable RBAC when initializing AgentOS:

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.os.config import AuthorizationConfig

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    id="my-agent",
    model=OpenAIChat(id="gpt-4o"),
    db=db,
)

agent_os = AgentOS(
    id="my-agent-os",
    agents=[agent],
    authorization=True,
)

app = agent_os.get_app()

It is required to set the JWT_VERIFICATION_KEY environment variable to the public key of the JWT verification key in the default case.If you want more control, you can use the AuthorizationConfig class:

from agno.os.config import AuthorizationConfig

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

You can also use a JWKS (JSON Web Key Set) file to verify JWTs instead of directly passing verification keys. To do this, provide the jwks_file parameter in the AuthorizationConfig:

from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    id="my-agent-os",
    agents=[agent],
    authorization=True,
    authorization_config=AuthorizationConfig(
        jwks_file="/path/to/jwks.json",
        algorithm="RS256",
    ),
)

or set the JWT_JWKS_FILE environment variable to point to a JWKS file.

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

Scope Format

RBAC uses a hierarchical scope format with three levels:

Global Resource Scopes

Format: resource:action Grants access to all resources of a type.

agents:read      # Read/list all agents
agents:run       # Run any agent
teams:read       # Read/list all teams
workflows:run    # Run any workflow
sessions:write   # Create/update any session

Per-Resource Scopes

Format: resource:<resource-id>:action Grants access to a specific resource.

agents:my-agent:read      # Read specific agent
agents:web-search:run     # Run specific agent
teams:research-team:run   # Run specific team
workflows:etl-pipeline:run # Run specific workflow

Wildcard Scopes

Format: resource:*:action Grants access to any resource of a type (equivalent to global).

agents:*:read     # Read any agent
teams:*:run       # Run any team

Admin Scope

The agent_os:admin scope grants full access to all endpoints.

agent_os:admin    # Full admin access

Complete Scope Reference

All available scopes for AgentOS RBAC. Scopes follow the format resource:action for global access or resource:<id>:action for per-resource access.

Admin Scopes

Scope	Description
`agent_os:admin`	Full admin access - grants access to all endpoints

System Scopes

Scope	Description
`system:read`	View system configuration and available models (`GET /config`, `GET /models`)

Agent Scopes

Scope	Description
`agents:read`	List and view all agents
`agents:write`	Create and update agents
`agents:delete`	Delete agents
`agents:run`	Run any agent
`agents:<agent-id>:read`	View a specific agent
`agents:<agent-id>:run`	Run a specific agent
`agents:*:read`	View any agent (wildcard)
`agents:*:run`	Run any agent (wildcard)

Team Scopes

Scope	Description
`teams:read`	List and view all teams
`teams:write`	Create and update teams
`teams:delete`	Delete teams
`teams:run`	Run any team
`teams:<team-id>:read`	View a specific team
`teams:<team-id>:run`	Run a specific team
`teams:*:read`	View any team (wildcard)
`teams:*:run`	Run any team (wildcard)

Workflow Scopes

Scope	Description
`workflows:read`	List and view all workflows
`workflows:write`	Create and update workflows
`workflows:delete`	Delete workflows
`workflows:run`	Run any workflow
`workflows:<workflow-id>:read`	View a specific workflow
`workflows:<workflow-id>:run`	Run a specific workflow
`workflows:*:read`	View any workflow (wildcard)
`workflows:*:run`	Run any workflow (wildcard)

Session Scopes

Scope	Description
`sessions:read`	View all sessions and session data
`sessions:write`	Create, update, and rename sessions
`sessions:delete`	Delete sessions

Memory Scopes

Scope	Description
`memories:read`	View memories, memory topics, and user memory stats
`memories:write`	Create, update, and optimize memories
`memories:delete`	Delete memories

Knowledge Scopes

Scope	Description
`knowledge:read`	View knowledge content, config, and search knowledge
`knowledge:write`	Add and update knowledge content
`knowledge:delete`	Delete knowledge content

Metrics Scopes

Scope	Description
`metrics:read`	View metrics
`metrics:write`	Refresh metrics

Evaluation Scopes

Scope	Description
`evals:read`	View evaluation runs
`evals:write`	Create and update evaluation runs
`evals:delete`	Delete evaluation runs

Default Scope Mappings

AgentOS automatically maps endpoints to required scopes. Here are all default mappings:

Endpoint	Required Scope
`GET /config`	`system:read`
`GET /models`	`system:read`

For all of the following endpoints, the specific Agent scopes (e.g. agents:<agent-id>:read) are respected.

Endpoint	Required Scope
`GET /agents`	`agents:read`
`GET /agents/*`	`agents:read`
`POST /agents`	`agents:write`
`PATCH /agents/*`	`agents:write`
`DELETE /agents/*`	`agents:delete`
`POST /agents/*/runs`	`agents:run`
`POST /agents//runs//continue`	`agents:run`
`POST /agents//runs//cancel`	`agents:run`

For all of the following endpoints, the specific Team scopes (e.g. teams:<team-id>:read) are respected.

Endpoint	Required Scope
`GET /teams`	`teams:read`
`GET /teams/*`	`teams:read`
`POST /teams`	`teams:write`
`PATCH /teams/*`	`teams:write`
`DELETE /teams/*`	`teams:delete`
`POST /teams/*/runs`	`teams:run`
`POST /teams//runs//continue`	`teams:run`
`POST /teams//runs//cancel`	`teams:run`

For all of the following endpoints, the specific Workflow scopes (e.g. workflows:<workflow-id>:read) are respected.

Endpoint	Required Scope
`GET /workflows`	`workflows:read`
`GET /workflows/*`	`workflows:read`
`POST /workflows`	`workflows:write`
`PATCH /workflows/*`	`workflows:write`
`DELETE /workflows/*`	`workflows:delete`
`POST /workflows/*/runs`	`workflows:run`
`POST /workflows//runs//continue`	`workflows:run`
`POST /workflows//runs//cancel`	`workflows:run`

Endpoint	Required Scope
`GET /sessions`	`sessions:read`
`GET /sessions/*`	`sessions:read`
`POST /sessions`	`sessions:write`
`POST /sessions/*/rename`	`sessions:write`
`PATCH /sessions/*`	`sessions:write`
`DELETE /sessions`	`sessions:delete`
`DELETE /sessions/*`	`sessions:delete`

Endpoint	Required Scope
`GET /memories`	`memories:read`
`GET /memories/*`	`memories:read`
`GET /memory_topics`	`memories:read`
`GET /user_memory_stats`	`memories:read`
`POST /memories`	`memories:write`
`PATCH /memories/*`	`memories:write`
`POST /optimize-memories`	`memories:write`
`DELETE /memories`	`memories:delete`
`DELETE /memories/*`	`memories:delete`

Endpoint	Required Scope
`GET /knowledge/content`	`knowledge:read`
`GET /knowledge/content/*`	`knowledge:read`
`GET /knowledge/config`	`knowledge:read`
`POST /knowledge/search`	`knowledge:read`
`POST /knowledge/content`	`knowledge:write`
`PATCH /knowledge/content/*`	`knowledge:write`
`DELETE /knowledge/content`	`knowledge:delete`
`DELETE /knowledge/content/*`	`knowledge:delete`

Endpoint	Required Scope
`GET /metrics`	`metrics:read`
`POST /metrics/refresh`	`metrics:write`

Endpoint	Required Scope
`GET /eval-runs`	`evals:read`
`GET /eval-runs/*`	`evals:read`
`POST /eval-runs`	`evals:write`
`PATCH /eval-runs/*`	`evals:write`
`DELETE /eval-runs`	`evals:delete`

Custom Scope Mappings

You can customize or extend the default scope mappings using the JWT middleware directly:

custom_scopes.py

from agno.os import AgentOS
from agno.os.middleware import JWTMiddleware

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    # Don't use built-in authorization - we'll configure JWT middleware manually
)

app = agent_os.get_app()

# Add JWT middleware with custom scope mappings
app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-jwt-key"],
    algorithm="RS256",
    authorization=True,  # Enable RBAC
    scope_mappings={
        # Override default scope for this endpoint
        "GET /agents": ["custom:read"],
        # Add scope for custom endpoint
        "POST /custom/endpoint": ["custom:write"],
        # Allow access without scopes (empty list)
        "GET /public/stats": [],
    }
)

Custom scope mappings are additive to the default mappings. To override a default mapping, specify the same route pattern with your custom scopes.

JWT Token Structure

When using RBAC, your JWT tokens should include:

{
  "sub": "user-123",
  "scopes": ["agents:read", "agents:my-agent:run"],
  "exp": 1735689600,
  "iat": 1735603200
}

Required Claims

Claim	Description
`scopes`	Array of permission scopes

Optional Claims

Claim	Description
`sub`	User ID (extracted as `user_id`)
`session_id`	Session ID for session tracking
`aud`	Audience - must match AgentOS `id` (when `verify_audience=True`)

Examples

Grant Read-Only Access

{
  "scopes": ["agents:read", "teams:read", "sessions:read"]
}

Grant Run and Read Access to Specific Agent

{
  "scopes": ["agents:my-agent:run", "agents:my-agent:read", "sessions:write"]
}

Grant Full Access to All Agents

{
  "scopes": ["agents:read", "agents:run", "sessions:read", "sessions:write"]
}

Admin Access

{
  "scopes": ["agent_os:admin"]
}

Excluded Routes

The following routes are excluded from RBAC checks by default:

/ (home)
/health
/docs
/redoc
/openapi.json
/docs/oauth2-redirect

Error Responses

Status Code	Description
`401 Unauthorized`	Missing or invalid JWT token
`401 Unauthorized`	Invalid audience (token not for this AgentOS)
`403 Forbidden`	Insufficient scopes for the requested operation

Examples

Basic RBAC

Basic RBAC example.

Advanced Scopes

Advanced RBAC example.

Per-Agent Permissions

Grant specific permissions to specific agents.

Custom Scope Mappings

Customize or extend the default scope mappings.

Developer Resources

AuthorizationConfig Reference

Configuration options for JWT verification.

JWTMiddleware Reference

Complete JWT middleware class reference.

Get Started

AgentOS

Usage

​Quick Start

​Scope Format

​Global Resource Scopes

​Per-Resource Scopes

​Wildcard Scopes

​Admin Scope

​Complete Scope Reference

​Admin Scopes

​System Scopes

​Agent Scopes

​Team Scopes

​Workflow Scopes

​Session Scopes

​Memory Scopes

​Knowledge Scopes

​Metrics Scopes

​Evaluation Scopes

​Default Scope Mappings

​Custom Scope Mappings

​JWT Token Structure

​Required Claims

​Optional Claims

​Examples

​Grant Read-Only Access

​Grant Run and Read Access to Specific Agent

​Grant Full Access to All Agents

​Admin Access

​Excluded Routes

​Error Responses

​Examples

Basic RBAC

Advanced Scopes

Per-Agent Permissions

Custom Scope Mappings

​Developer Resources

AuthorizationConfig Reference

JWTMiddleware Reference

Quick Start

Scope Format

Global Resource Scopes

Per-Resource Scopes

Wildcard Scopes

Admin Scope

Complete Scope Reference

Admin Scopes

System Scopes

Agent Scopes

Team Scopes

Workflow Scopes

Session Scopes

Memory Scopes

Knowledge Scopes

Metrics Scopes

Evaluation Scopes

Default Scope Mappings

Custom Scope Mappings

JWT Token Structure

Required Claims

Optional Claims

Examples

Grant Read-Only Access

Grant Run and Read Access to Specific Agent

Grant Full Access to All Agents

Admin Access

Excluded Routes

Error Responses

Examples

Developer Resources