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()

Generate a Verification Key

authorization=True only tells AgentOS to enforce JWT auth. To verify tokens, AgentOS also needs a public key. Generate one from the control plane and wire it in.

Toggle JWT authorization

Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.

Copy the public key

A modal appears with the public key for your AgentOS.

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"

Authorization is now active for your AgentOS.

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

Organization Scopes

Organization scopes are enforced at the control plane and do not map to AgentOS endpoints.

Scope	Description
`os:read`	View AgentOS instances in the organization
`os:write`	Create and update AgentOS instances
`os:delete`	Delete AgentOS instances
`org:read`	View organization details and members
`org:write`	Update organization settings and manage members
`org:delete`	Delete the organization
`billing:read`	View billing details and invoices
`billing:write`	Update billing settings and payment methods

Admin Scopes

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

AgentOS config Scopes

Scope	Description
`config:read`	View system configuration and available models
`config:write`	Administrative writes such as database migrations

Registry Scopes

Scope	Description
`registry:read`	View the code-defined registry (tools, models, databases)

Component Scopes

Scope	Description
`components:read`	List and view components and their configs
`components:write`	Create and update components and configs
`components:delete`	Delete components and configs

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`	`config:read`
`GET /models`	`config:read`
`POST /databases/all/migrate`	`config:write`
`POST /databases/*/migrate`	`config:write`

Endpoint	Required Scope
`GET /registry`	`registry: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`
`GET /knowledge/*/sources`	`knowledge:read`
`GET /knowledge//sources//files`	`knowledge:read`
`POST /knowledge/search`	`knowledge:read`
`POST /knowledge/content`	`knowledge:write`
`POST /knowledge/remote-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`
`POST /traces/search`	`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`

Endpoint	Required Scope
`GET /components`	`components:read`
`GET /components/*`	`components:read`
`GET /components/*/configs`	`components:read`
`GET /components//configs/`	`components:read`
`GET /components/*/configs/current`	`components:read`
`POST /components`	`components:write`
`POST /components/*/configs`	`components:write`
`POST /components//configs//set-current`	`components:write`
`PATCH /components/*`	`components:write`
`PATCH /components//configs/`	`components:write`
`DELETE /components/*`	`components:delete`
`DELETE /components//configs/`	`components:delete`

Access Prerequisites

A few scopes gate access to everything downstream. Without them, finer-grained scopes have no effect because the user cannot reach the resources they apply to.

Scope	Without it, the user cannot
`org:read`	Access the organization at all
`os:read`	List AgentOS instances in the organization
`config:read`	Use any AgentOS endpoint (the UI loads `/config` on startup)

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.

Custom Roles and Scopes

Custom roles and scopes are available on the Enterprise plan. Book a call or email support@agno.com to enable.

Custom roles require JWT authentication. Without it, scope enforcement is skipped entirely by AgentOS and assigned roles have no effect.

Compose scopes into named roles in the control plane and assign them to users in your organization. Members inherit the scopes of every role assigned to them.

Create a Custom Role

Open the Roles page in the control plane.
Define a role name and select the scopes it grants.
Save the role.

Assign a Role to a User

Open the Organization settings page and assign the role to a user.

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

Get Started

AgentOS

Example Usage

Documentation Index

​Quick Start

​Generate a Verification Key

​Scope Format

​Complete Scope Reference

​Organization Scopes

​Admin Scopes

​AgentOS config Scopes

​Registry Scopes

​Component 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

​Access Prerequisites

​Custom Scope Mappings

​Custom Roles and Scopes

​Create a Custom Role

​Assign a Role to a User

​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

Generate a Verification Key

Scope Format

Complete Scope Reference

Organization Scopes

Admin Scopes

AgentOS config Scopes

Registry Scopes

Component 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

Access Prerequisites

Custom Scope Mappings

Custom Roles and Scopes

Create a Custom Role

Assign a Role to a User

JWT Token Structure

Example Tokens

Configuration Options

Excluded Routes

Error Responses

Examples

Developer Resources