Skip to main content

​
Overview

AgentOS provides built-in Role-Based Access Control (RBAC) to secure your entire agentic system. RBAC validates uses JWT tokens as a way to represent the identity of the user making the request. Whether this user is coming from the AgentOS Control Plane or your own application, the JWT token is validated and the scopes are checked against the required permissions for each endpoint.
RBAC is the recommended way to secure your AgentOS instance. It provides fine-grained permissions and per-resource access control.

​
Role-Based Access Control (RBAC)

AgentOS supports built-in Role-Based Access Control (RBAC) to manage permissions for your agents, teams, and workflows. When enabled, RBAC validates JWT scopes against required permissions for each endpoint. Learn more about how identity and authorization flow in AgentOS RBAC in the RBAC documentation.

​
Enabling RBAC

Enable RBAC by setting authorization=True when initializing AgentOS:
rbac_enabled.py
from agno.os import AgentOS
from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    authorization=True,  # Enable authorization with RBAC
)

​
Configuring the Verification Key

JWT verification on AgentOS requires a verification key to check the signature of the JWT token. When authorization is enabled on the AgentOS Control Plane, all traffic to your AgentOS will have a JWT token attached. Agno generates a private/public key pair, and the private key is used to sign the token. The public key can then be used to verify the signature of the JWT token. The key will be generated when you enable authorization: When connecting a new OS during initial setup: From the Settings page when enabling authorization on an existing OS:
When RBAC is enabled, requests without a valid JWT token return 401 Unauthorized or 403 Forbidden if the scopes are insufficient.
Set this key in the following ways:
  • Copy the public key from the AgentOS Control Plane and set that manually on your AgentOS or via a JWT_VERIFICATION_KEY environment variable.
  • Download the JWKS file from the AgentOS Control Plane and set that manually on your AgentOS or via a JWT_JWKS_FILE environment variable to point to a JWKS file.
See the RBAC Documentation for more details.

​
Key Features

  • Automatic JWT Middleware: When authorization is enabled, AgentOS automatically adds JWT middleware
  • Scope-Based Permissions: Validates user scopes against required permissions per endpoint. See the scopes documentation for more details.
  • Per-Resource Access Control: Grant access to specific agents, teams, or workflows, both on retrieval and execution.
For a complete list of all features, available scopes and default endpoint mappings, see RBAC Documentation.

​
Developer Resources

RBAC Documentation

Complete RBAC scopes, permissions, and access control configuration.

JWT Middleware

JWT authentication with parameter injection and claims extraction.

​
Security Key Authentication (Deprecated)

Security Key authentication is deprecated. Use RBAC instead for fine-grained access control.
Security Key authentication provides simple bearer-token authentication but lacks the fine-grained permissions of RBAC.

​
Configuration

Set the OS_SECURITY_KEY environment variable: 
export OS_SECURITY_KEY="OSK_...your_key..."
And run your AgentOS application:
agent_os.py
from agno.os import AgentOS

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

if __name__ == "__main__":
    agent_os.serve(app="agent_os:app", reload=True)
When OS_SECURITY_KEY is configured, requests without a valid Authorization: Bearer <key> header return 401 Unauthorized.

​
Migrating to RBAC

If you are currently using Security Key authentication and want to migrate to RBAC:
  1. Enable RBAC by setting authorization=True on your AgentOS instance
  2. Set the JWT verification key via the JWT_VERIFICATION_KEY environment variable
  3. Unset the OS_SECURITY_KEY environment variable - this is important as having both set can cause unexpected authentication behavior where requests may be rejected or authenticated incorrectly
# Remove the old security key
unset OS_SECURITY_KEY

# Set the new JWT verification key
export JWT_VERIFICATION_KEY="your-public-key"
If OS_SECURITY_KEY remains set while RBAC is enabled, the security key checks will still be active and interfere with JWT authentication. Always ensure OS_SECURITY_KEY is unset in your environment when using RBAC.