Role-Based Access Control (RBAC)

AgentOS validates JWT scopes against required permissions for each endpoint. Control who can access and run your agents, teams, and workflows.

Quick Start

Enable RBAC when initializing AgentOS:

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

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

agent = Agent(
    id="my-agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
)

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

app = agent_os.get_app()

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"

Scope Format

RBAC uses a hierarchical scope format:

Format	Example	Description
`resource:action`	`agents:read`	Access all resources of a type
`resource:<id>:action`	`agents:my-agent:run`	Access a specific resource
`resource:*:action`	`agents:*:read`	Wildcard (equivalent to global)
`agent_os:admin`	-	Full access to all endpoints

Complete Scope Reference

Admin Scopes

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

System Scopes

Scope	Description
`system:read`	View system configuration and available 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

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

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

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 and memory topics
`memories:write`	Create, update, and optimize memories
`memories:delete`	Delete memories

Knowledge Scopes

Scope	Description
`knowledge:read`	View and search knowledge content
`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

Trace Scopes

Scope	Description
`traces:read`	View traces and trace sessions

Schedule Scopes

Scope	Description
`schedules:read`	List and view schedules and schedule runs
`schedules:write`	Create, update, enable, disable, and trigger schedules
`schedules:delete`	Delete schedules

Approval Scopes

Scope	Description
`approvals:read`	List and view approval requests
`approvals:write`	Resolve approval requests
`approvals:delete`	Delete approval requests

Default Scope Mappings

AgentOS automatically maps endpoints to required scopes.

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

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`

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`

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`

Endpoint	Required Scope
`GET /traces`	`traces:read`
`GET /traces/*`	`traces:read`
`GET /trace_session_stats`	`traces:read`

Endpoint	Required Scope
`GET /schedules`	`schedules:read`
`GET /schedules/*`	`schedules:read`
`GET /schedules/*/runs`	`schedules:read`
`GET /schedules//runs/`	`schedules:read`
`POST /schedules`	`schedules:write`
`PATCH /schedules/*`	`schedules:write`
`POST /schedules/*/enable`	`schedules:write`
`POST /schedules/*/disable`	`schedules:write`
`POST /schedules/*/trigger`	`schedules:write`
`DELETE /schedules/*`	`schedules:delete`

Endpoint	Required Scope
`GET /approvals`	`approvals:read`
`GET /approvals/count`	`approvals:read`
`GET /approvals/*`	`approvals:read`
`GET /approvals/*/status`	`approvals:read`
`POST /approvals/*/resolve`	`approvals:write`
`DELETE /approvals/*`	`approvals:delete`

Custom Scope Mappings

Customize or extend the default scope mappings using the JWT middleware:

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

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

app = agent_os.get_app()

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-jwt-key"],
    algorithm="RS256",
    authorization=True,
    scope_mappings={
        "GET /agents": ["custom:read"],
        "POST /custom/endpoint": ["custom:write"],
        "GET /public/stats": [],  # No scopes required
    }
)

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

JWT Token Structure

Your JWT tokens should include:

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

Claim	Required	Description
`scopes`	Yes	Array of permission scopes
`sub`	No	User ID (extracted as `user_id`)
`session_id`	No	Session ID for session tracking
`aud`	No	Audience (must match AgentOS `id` when `verify_audience=True`)

Example Tokens

Read-only access:

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

Run a specific agent:

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

Admin access:

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

Configuration Options

Configure JWT verification using AuthorizationConfig:

from agno.os import AgentOS
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 file:

authorization_config=AuthorizationConfig(
    jwks_file="/path/to/jwks.json",
    algorithm="RS256",
)

Or set environment variables:

export JWT_VERIFICATION_KEY="your-public-key"
# or
export JWT_JWKS_FILE="/path/to/jwks.json"

Excluded Routes

These routes are excluded from RBAC checks by default: /, /health, /docs, /redoc, /openapi.json, /docs/oauth2-redirect

Error Responses

Status Code	Description
`401 Unauthorized`	Missing or invalid JWT token
`403 Forbidden`	Insufficient scopes for the requested operation

Role-Based Access Control (RBAC)

Quick Start

Scope Format

Complete Scope Reference

Admin Scopes

System Scopes

Agent Scopes

Team Scopes

Workflow Scopes

Session Scopes

Memory Scopes

Knowledge Scopes

Metrics Scopes

Evaluation Scopes

Trace Scopes

Schedule Scopes

Approval Scopes

Default Scope Mappings

Custom Scope Mappings

JWT Token Structure

Example Tokens

Configuration Options

Excluded Routes

Error Responses

Examples

Basic RBAC

Per-Agent Permissions

Developer Resources

AuthorizationConfig Reference

JWTMiddleware Reference

​Quick Start

​Scope Format

​Complete Scope Reference

​Admin Scopes

​System Scopes

​Agent Scopes

​Team Scopes

​Workflow Scopes

​Session Scopes

​Memory Scopes

​Knowledge Scopes

​Metrics Scopes

​Evaluation Scopes

​Trace Scopes

​Schedule Scopes

​Approval Scopes

​Default Scope Mappings

​Custom Scope Mappings

​JWT Token Structure

​Example Tokens

​Configuration Options

​Excluded Routes

​Error Responses

​Examples

Basic RBAC

Per-Agent Permissions

​Developer Resources

AuthorizationConfig Reference

JWTMiddleware Reference

Quick Start

Scope Format

Complete Scope Reference

Admin Scopes

System Scopes

Agent Scopes

Team Scopes

Workflow Scopes

Session Scopes

Memory Scopes

Knowledge Scopes

Metrics Scopes

Evaluation Scopes

Trace Scopes

Schedule Scopes

Approval Scopes

Default Scope Mappings

Custom Scope Mappings

JWT Token Structure

Example Tokens

Configuration Options

Excluded Routes

Error Responses

Examples

Developer Resources