diff --git a/agent-os/api/authentication.mdx b/agent-os/api/authentication.mdx
index e13d094c2..cdea6d2af 100644
--- a/agent-os/api/authentication.mdx
+++ b/agent-os/api/authentication.mdx
@@ -49,7 +49,7 @@ Your JWT tokens should include scopes and audience claims:
 | `sessions:write` | Create/update sessions |
 | `agent_os:admin` | Full admin access |
 
-See [RBAC Documentation](/agent-os/security/rbac) for all available scopes.
+See [Scopes](/agent-os/security/authorization/scopes) for all available scopes.
 
 ### Error Responses
 
@@ -67,12 +67,12 @@ See [RBAC Documentation](/agent-os/security/rbac) for all available scopes.
     icon="shield"
     href="/agent-os/security/overview"
   >
-    Enable RBAC and configure authorization.
+    Enable authorization and configure JWT verification.
   </Card>
   <Card
-    title="RBAC"
+    title="Authorization"
     icon="lock"
-    href="/agent-os/security/rbac"
+    href="/agent-os/security/authorization/overview"
   >
     Complete scope reference and endpoint mappings.
   </Card>
diff --git a/agent-os/control-plane.mdx b/agent-os/control-plane.mdx
index 16ef846bc..6702d87dc 100644
--- a/agent-os/control-plane.mdx
+++ b/agent-os/control-plane.mdx
@@ -254,7 +254,7 @@ Enable JWT verification and generate key pairs from the control plane, either wh
   </video>
 </Frame>
 
-See [AgentOS Security](/agent-os/security/overview) and [RBAC](/agent-os/security/rbac) for setup details.
+See [AgentOS Security](/agent-os/security/overview) and [Authorization](/agent-os/security/authorization/overview) for setup details.
 
 ## User Management
 
@@ -268,7 +268,7 @@ Every organization has three default roles. Custom roles are available on the En
 | **Administrator** | Manage members, roles, settings, and resources; cannot update billing or delete the organization |
 | **Member** | Run and edit AgentOS resources; cannot delete resources or manage members |
 
-See [RBAC](/agent-os/security/rbac) for the full capability matrix and custom role setup.
+See [Roles](/agent-os/security/authorization/roles) for the full capability matrix and custom role setup.
 
 <Frame>
   <video
diff --git a/agent-os/middleware/jwt.mdx b/agent-os/middleware/jwt.mdx
index f262fd501..6343a7db8 100644
--- a/agent-os/middleware/jwt.mdx
+++ b/agent-os/middleware/jwt.mdx
@@ -173,6 +173,25 @@ Use strong verification keys, store them securely (not in code), and enable vali
 - Set `samesite="strict"` for CSRF protection
 </Tip>
 
+## Local Development
+
+<Warning>
+Do not use `validate=False` in production. The middleware decodes claims without verifying the JWT signature.
+</Warning>
+
+Skip signature verification in local development, or when an upstream API gateway already validates JWTs.
+
+```python
+from agno.os.middleware.jwt import JWTMiddleware
+
+app.add_middleware(
+    JWTMiddleware,
+    validate=False,
+)
+```
+
+No verification key is required. Claims are extracted from the token but not authenticated.
+
 ## RBAC Authorization
 
 Enable Role-Based Access Control (RBAC) to validate JWT scopes against required permissions:
@@ -222,7 +241,7 @@ app.add_middleware(
 ```
 
 <Tip>
-For detailed RBAC documentation including all available scopes and default mappings, see [RBAC Documentation](/agent-os/security/rbac).
+For all available scopes and default endpoint mappings, see [Scopes](/agent-os/security/authorization/scopes).
 </Tip>
 
 
@@ -312,11 +331,11 @@ See the [JWTMiddleware Reference](/reference/agent-os/jwt-middleware) for the co
     Custom FastAPI app with JWT middleware and AgentOS integration.
   </Card>
   <Card
-    title="RBAC Documentation"
+    title="Authorization"
     icon="lock"
-    href="/agent-os/security/rbac"
+    href="/agent-os/security/authorization/overview"
   >
-    Detailed RBAC scopes, permissions, and access control configuration.
+    Scopes, roles, and access control configuration.
   </Card>
   <Card
     title="JWTMiddleware Reference"
diff --git a/agent-os/middleware/overview.mdx b/agent-os/middleware/overview.mdx
index de71ab0b8..4f2f8b061 100644
--- a/agent-os/middleware/overview.mdx
+++ b/agent-os/middleware/overview.mdx
@@ -30,11 +30,11 @@ See the following guides:
     Built-in JWT authentication with automatic parameter injection and claims extraction.
   </Card>
   <Card
-    title="RBAC"
+    title="Authorization"
     icon="lock"
-    href="/agent-os/security/rbac"
+    href="/agent-os/security/authorization/overview"
   >
-    Use the built-in JWT middleware with Role-based access control and fine-grained permission scopes.
+    JWT validation with role-based access control and fine-grained permission scopes.
   </Card>
 </CardGroup>
 
@@ -104,7 +104,7 @@ Test middleware thoroughly in your own staging environment before production dep
     - Admin scope for full access
     - Customizable scope mappings
     
-    [Learn more about RBAC](/agent-os/security/rbac)
+    [Authorization](/agent-os/security/authorization/overview)
   </Tab>
   
   <Tab title="Rate Limiting">
@@ -195,11 +195,11 @@ app.add_middleware(MiddlewareC)  # Runs first (outermost)
     Custom FastAPI app with JWT middleware and AgentOS integration.
   </Card>
   <Card
-    title="RBAC Documentation"
+    title="Authorization"
     icon="lock"
-    href="/agent-os/security/rbac"
+    href="/agent-os/security/authorization/overview"
   >
-    Detailed RBAC scopes, permissions, and access control.
+    Scopes, roles, and access control.
   </Card>
 </CardGroup>
 
diff --git a/agent-os/overview.mdx b/agent-os/overview.mdx
index 4b2fc0d66..ebe1550d5 100644
--- a/agent-os/overview.mdx
+++ b/agent-os/overview.mdx
@@ -39,7 +39,7 @@ if __name__ == "__main__":
 | `config`                  | `str` or `AgentOSConfig` | `None`  | Configuration path or object ([docs](/agent-os/config))        |
 | `base_app`                | `FastAPI`                | `None`  | Custom FastAPI app ([docs](/agent-os/custom-fastapi/overview)) |
 | `lifespan`                | `Any`                    | `None`  | Lifespan context manager ([docs](/agent-os/lifespan))          |
-| `authorization`           | `bool`                   | `False` | Enable RBAC ([docs](/agent-os/security/rbac))                  |
+| `authorization`           | `bool`                   | `False` | Enable authorization ([docs](/agent-os/security/authorization/overview))                  |
 | `authorization_config`    | `AuthorizationConfig`    | `None`  | JWT verification config                                        |
 | `enable_mcp_server`       | `bool`                   | `False` | Enable MCP server ([docs](/agent-os/mcp/mcp))                  |
 | `cors_allowed_origins`    | `List[str]`              | `None`  | Allowed CORS origins                                           |
diff --git a/agent-os/security/authorization/customization.mdx b/agent-os/security/authorization/customization.mdx
new file mode 100644
index 000000000..f1eb4a12e
--- /dev/null
+++ b/agent-os/security/authorization/customization.mdx
@@ -0,0 +1,41 @@
+---
+title: "Customization"
+sidebarTitle: "Customization"
+description: "Override scope mappings to add custom endpoints or change defaults."
+---
+
+Customize or extend the default scope mappings using the JWT middleware:
+
+```python
+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.
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| Configure JWT middleware in depth | [JWT Middleware](/agent-os/middleware/jwt) |
+| See the custom scope mappings example | [Custom scope mappings](/agent-os/usage/rbac/custom-scope-mappings) |
+| Reference the middleware class | [JWTMiddleware Reference](/reference/agent-os/jwt-middleware) |
diff --git a/agent-os/security/authorization/overview.mdx b/agent-os/security/authorization/overview.mdx
new file mode 100644
index 000000000..9fe8bfda4
--- /dev/null
+++ b/agent-os/security/authorization/overview.mdx
@@ -0,0 +1,135 @@
+---
+title: "Authorization"
+sidebarTitle: "Overview"
+description: "JWT validation and scope-based permissions for AgentOS endpoints."
+---
+
+AgentOS validates the JWT on every request, then checks its scopes against the permissions each endpoint requires. This controls who can access and run your agents, teams, and workflows.
+
+<img
+  className="block dark:hidden"
+  src="/images/jwt-verification-light.png"
+  alt="JWT verification flow"
+/>
+
+<img
+  className="hidden dark:block"
+  src="/images/jwt-verification-dark.png"
+  alt="JWT verification flow"
+/>
+
+Enable authorization when initializing AgentOS:
+
+```python
+from agno.agent import Agent
+from agno.models.openai import OpenAIResponses
+from agno.os import AgentOS
+
+
+agent = Agent(
+    id="my-agent",
+    model=OpenAIResponses(id="gpt-5.2"),
+)
+
+agent_os = AgentOS(
+    id="my-agent-os",
+    agents=[agent],
+    authorization=True,
+)
+
+app = agent_os.get_app()
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Tokens | JWTs signed by the control plane or your own backend, sent as `Authorization: Bearer <token>` |
+| Scopes | Permission strings in the `scopes` claim, like `agents:read` or `agents:my-agent:run` |
+| Roles | Named bundles of scopes assigned to users (Owner, Administrator, Member, or custom) |
+| Isolation | Per-user data scoping for sessions, memories, and traces |
+
+## Learn How To
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="play" href="/agent-os/security/authorization/quickstart">
+    Enable authorization, set a verification key, and make your first authenticated request.
+  </Card>
+  <Card title="JSON Web Tokens (JWT)" icon="key" href="/agent-os/security/authorization/tokens">
+    JWT claim structure, example tokens, and how AgentOS reads them.
+  </Card>
+  <Card title="Self-Hosted (BYO Token)" icon="server" href="/agent-os/security/authorization/self-hosted">
+    Run AgentOS without the control plane by issuing and verifying your own JWTs.
+  </Card>
+  <Card title="Scopes" icon="shield" href="/agent-os/security/authorization/scopes">
+    Scope format and the full permission reference for every AgentOS endpoint.
+  </Card>
+  <Card title="Roles" icon="users" href="/agent-os/security/authorization/roles">
+    Default roles and custom roles defined in the control plane.
+  </Card>
+  <Card title="Per-User Data Isolation" icon="user-lock" href="/agent-os/security/authorization/user-isolation">
+    Scope sessions, memories, and traces to the caller's user ID.
+  </Card>
+  <Card title="Customization" icon="sliders" href="/agent-os/security/authorization/customization">
+    Override scope mappings to add custom endpoints or change defaults.
+  </Card>
+</CardGroup>
+
+## Examples
+
+<CardGroup cols={2}>
+  <Card
+    title="Basic Authorization (Symmetric)"
+    icon="lock"
+    href="/agent-os/usage/rbac/basic-symmetric"
+  >
+    Enable authorization with a shared-secret JWT (HS256).
+  </Card>
+  <Card
+    title="Basic Authorization (Asymmetric)"
+    icon="key"
+    href="/agent-os/usage/rbac/basic-asymmetric"
+  >
+    Sign with a private key, verify with the public key (RS256).
+  </Card>
+  <Card
+    title="Per-Agent Permissions"
+    icon="user"
+    href="/agent-os/usage/rbac/per-agent-permissions"
+  >
+    Grant specific permissions to specific agents.
+  </Card>
+  <Card
+    title="Per-User Data Isolation"
+    icon="users"
+    href="https://github.com/agno-agi/agno/blob/main/cookbook/05_agent_os/rbac/symmetric/user_isolation.py"
+  >
+    Scope sessions, memory, and traces per user with `user_isolation=True`.
+  </Card>
+</CardGroup>
+
+## Developer Resources
+
+<CardGroup cols={2}>
+  <Card
+    title="JWT Middleware"
+    icon="key"
+    href="/agent-os/middleware/jwt"
+  >
+    Configure token sources, claim extraction, and scope checking.
+  </Card>
+  <Card
+    title="AuthorizationConfig Reference"
+    icon="gear"
+    href="/reference/agent-os/authorization-config"
+  >
+    Configuration options for JWT verification.
+  </Card>
+  <Card
+    title="JWTMiddleware Reference"
+    icon="code"
+    href="/reference/agent-os/jwt-middleware"
+  >
+    Complete JWT middleware class reference.
+  </Card>
+</CardGroup>
diff --git a/agent-os/security/authorization/quickstart.mdx b/agent-os/security/authorization/quickstart.mdx
new file mode 100644
index 000000000..1e1c80312
--- /dev/null
+++ b/agent-os/security/authorization/quickstart.mdx
@@ -0,0 +1,133 @@
+---
+title: "Quickstart"
+sidebarTitle: "Quickstart"
+description: "Enable authorization, set a verification key, and make your first authenticated request."
+---
+
+```python
+from agno.agent import Agent
+from agno.models.openai import OpenAIResponses
+from agno.os import AgentOS
+
+
+agent = Agent(
+    id="my-agent",
+    model=OpenAIResponses(id="gpt-5.2"),
+)
+
+agent_os = AgentOS(
+    id="my-agent-os",
+    agents=[agent],
+    authorization=True,
+)
+
+app = agent_os.get_app()
+```
+
+`authorization=True` enables JWT verification. AgentOS also needs a public key to verify tokens against. Generate one from the control plane and wire it in.
+
+## Generate a Verification Key
+
+<Steps>
+  <Step title="Toggle JWT authorization">
+    Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.
+  </Step>
+
+  <Step title="Copy the public key">
+    Copy the public key for your AgentOS from the modal.
+  </Step>
+
+  <Step title="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:
+    ```bash
+    export JWT_VERIFICATION_KEY="your-public-key"
+    ```
+
+    Or, if you manage keys via a JWKS file, point AgentOS at it instead:
+    ```bash
+    export JWT_JWKS_FILE="/path/to/jwks.json"
+    ```
+  </Step>
+</Steps>
+
+Authorization is now active for your AgentOS.
+
+<Note>
+The control plane only issues **RS256** keys, which is also the default. See [authorization troubleshooting](/faq/rbac-auth-failed) for common setup issues.
+</Note>
+
+<video
+  autoPlay
+  muted
+  controls
+  className="w-full aspect-video"
+  src="/videos/auth-on-connect-web.mp4"
+></video>
+
+## Configurable Options
+
+Configure JWT verification using `AuthorizationConfig`:
+
+```python
+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",
+    ),
+)
+```
+
+Use a JWKS file instead:
+
+```python
+authorization_config=AuthorizationConfig(
+    jwks_file="/path/to/jwks.json",
+    algorithm="RS256",
+)
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `JWT_VERIFICATION_KEY` | Single public key or shared secret. Added to `verification_keys`. |
+| `JWT_JWKS_FILE` | Path to a static JWKS file. |
+| `JWT_JWKS` | Inline JWKS JSON. |
+
+Env vars work alongside `AuthorizationConfig`. Pass keys in code, env vars, or both.
+
+## Sending Authenticated Requests
+
+Send the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agents
+```
+
+## Excluded Routes
+
+These routes are excluded from authorization checks by default:
+
+`/`, `/health`, `/info`, `/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 |
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| Understand JWT claim structure | [Tokens](/agent-os/security/authorization/tokens) |
+| Issue tokens from your own backend | [Self-Hosted](/agent-os/security/authorization/self-hosted) |
+| See the full scope reference | [Scopes](/agent-os/security/authorization/scopes) |
+| Assign roles to users | [Roles](/agent-os/security/authorization/roles) |
diff --git a/agent-os/security/authorization/roles.mdx b/agent-os/security/authorization/roles.mdx
new file mode 100644
index 000000000..707d87b62
--- /dev/null
+++ b/agent-os/security/authorization/roles.mdx
@@ -0,0 +1,65 @@
+---
+title: "Roles"
+sidebarTitle: "Roles"
+description: "Default and custom roles in the AgentOS control plane."
+---
+
+Roles are named bundles of scopes assigned to users. Members inherit the scopes of every role assigned to them.
+
+<Note>
+The roles on this page are managed in the [AgentOS control plane](https://os.agno.com). If you're running [self-hosted](/agent-os/security/authorization/self-hosted), define roles in your identity provider or backend and include the appropriate scopes in the JWT.
+</Note>
+
+## Default Roles
+
+The AgentOS control plane provides three default roles for organization members.
+
+| Capability                          | Owner | Administrator | Member |
+|-------------------------------------|:-----:|:-------------:|:------:|
+| Run agents, teams, workflows        |   ✓   |       ✓       |   ✓    |
+| Create and update AgentOS resources |   ✓   |       ✓       |   ✓    |
+| Delete AgentOS resources            |   ✓   |       ✓       |        |
+| Create and update AgentOS instances |   ✓   |       ✓       |   ✓    |
+| Delete AgentOS instances            |   ✓   |               |        |
+| Manage members and roles            |   ✓   |       ✓       |        |
+| Update organization settings        |   ✓   |       ✓       |        |
+| View billing                        |   ✓   |       ✓       |   ✓    |
+| Update billing                      |   ✓   |               |        |
+| Delete the organization             |   ✓   |               |        |
+
+## Custom Roles
+
+<Note>
+Custom roles and scopes are available on the Enterprise plan. [Book a call](https://cal.com/team/agno/intro) or email [support@agno.com](mailto:support@agno.com) to enable.
+</Note>
+
+<Warning>
+Custom roles require JWT authentication. Without it, scope enforcement is skipped entirely by AgentOS and assigned roles have no effect.
+</Warning>
+
+Compose scopes into named roles in the AgentOS control plane and assign them to users in your organization.
+
+### Create a Custom Role
+
+1. Open the [Roles page](https://os.agno.com/settings/roles) in the control plane.
+2. Define a role name and select the scopes it grants.
+3. Save the role.
+
+### Assign a Role to a User
+
+Open the [Organization settings page](https://os.agno.com/settings/organization) and assign the role to a user.
+
+<video
+  autoPlay
+  muted
+  controls
+  className="w-full aspect-video"
+  src="/videos/roles.mp4"
+></video>
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| See the full scope reference | [Scopes](/agent-os/security/authorization/scopes) |
+| Isolate data per user | [Per-User Data Isolation](/agent-os/security/authorization/user-isolation) |
diff --git a/agent-os/security/authorization/scopes.mdx b/agent-os/security/authorization/scopes.mdx
new file mode 100644
index 000000000..846840f10
--- /dev/null
+++ b/agent-os/security/authorization/scopes.mdx
@@ -0,0 +1,230 @@
+---
+title: "Scopes"
+sidebarTitle: "Scopes"
+description: "Scope format and the full permission reference for every AgentOS endpoint."
+---
+
+Scopes are permission strings in the JWT `scopes` claim. Each AgentOS endpoint requires one or more scopes; requests with insufficient scopes return `403 Forbidden`.
+
+## Scope Format
+
+Scopes are hierarchical:
+
+| 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 |
+
+## Scope Reference
+
+Scopes split across two enforcement layers. AgentOs control plane scopes are checked by the control plane. AgentOS scopes are checked by your runtime against incoming requests.
+
+Any `resource:action` scope also accepts a `resource:<id>:action` form to limit access to a specific resource. See [Scope Format](#scope-format).
+
+The `agent_os:admin` scope grants full access to every AgentOS endpoint below.
+
+### AgentOS Control Plane Scopes
+
+| 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 |
+| `org:write` | Update organization details |
+| `org:delete` | Delete the organization |
+| `org:members:read` | View organization members |
+| `org:members:write` | Invite and update organization members |
+| `org:roles:read` | View organization roles and their scope assignments |
+| `org:roles:write` | Create and update organization role scopes |
+| `org:roles:delete` | Delete organization roles |
+| `billing:read` | View billing details and invoices |
+| `billing:write` | Update billing settings and payment methods |
+
+### AgentOS Scopes
+
+<Tabs>
+  <Tab title="Config">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `config:read` | `GET /config` | Read the OS configuration |
+    | `config:read` | `GET /models` | List available models |
+    | `config:write` | `POST /databases/all/migrate` | Run migrations on all databases |
+    | `config:write` | `POST /databases/*/migrate` | Run migrations on a specific database |
+  </Tab>
+
+  <Tab title="Registry">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `registry:read` | `GET /registry` | View the code-defined registry (tools, models, databases) |
+  </Tab>
+
+  <Tab title="Components">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `components:read` | `GET /components` | List components |
+    | `components:read` | `GET /components/*` | View a component |
+    | `components:read` | `GET /components/*/configs` | List a component's configs |
+    | `components:read` | `GET /components/*/configs/*` | View a component config |
+    | `components:read` | `GET /components/*/configs/current` | View the current component config |
+    | `components:write` | `POST /components` | Create a component |
+    | `components:write` | `POST /components/*/configs` | Create a component config |
+    | `components:write` | `POST /components/*/configs/*/set-current` | Mark a config as current |
+    | `components:write` | `PATCH /components/*` | Update a component |
+    | `components:write` | `PATCH /components/*/configs/*` | Update a component config |
+    | `components:delete` | `DELETE /components/*` | Delete a component |
+    | `components:delete` | `DELETE /components/*/configs/*` | Delete a component config |
+  </Tab>
+
+  <Tab title="Agents">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `agents:read` | `GET /agents` | List agents |
+    | `agents:read` | `GET /agents/*` | View an agent |
+    | `agents:write` | `POST /agents` | Create an agent |
+    | `agents:write` | `PATCH /agents/*` | Update an agent |
+    | `agents:delete` | `DELETE /agents/*` | Delete an agent |
+    | `agents:run` | `POST /agents/*/runs` | Run an agent |
+    | `agents:run` | `POST /agents/*/runs/*/continue` | Continue a paused run |
+    | `agents:run` | `POST /agents/*/runs/*/cancel` | Cancel a run |
+  </Tab>
+
+  <Tab title="Teams">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `teams:read` | `GET /teams` | List teams |
+    | `teams:read` | `GET /teams/*` | View a team |
+    | `teams:write` | `POST /teams` | Create a team |
+    | `teams:write` | `PATCH /teams/*` | Update a team |
+    | `teams:delete` | `DELETE /teams/*` | Delete a team |
+    | `teams:run` | `POST /teams/*/runs` | Run a team |
+    | `teams:run` | `POST /teams/*/runs/*/continue` | Continue a paused run |
+    | `teams:run` | `POST /teams/*/runs/*/cancel` | Cancel a run |
+  </Tab>
+
+  <Tab title="Workflows">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `workflows:read` | `GET /workflows` | List workflows |
+    | `workflows:read` | `GET /workflows/*` | View a workflow |
+    | `workflows:write` | `POST /workflows` | Create a workflow |
+    | `workflows:write` | `PATCH /workflows/*` | Update a workflow |
+    | `workflows:delete` | `DELETE /workflows/*` | Delete a workflow |
+    | `workflows:run` | `POST /workflows/*/runs` | Run a workflow |
+    | `workflows:run` | `POST /workflows/*/runs/*/continue` | Continue a paused run |
+    | `workflows:run` | `POST /workflows/*/runs/*/cancel` | Cancel a run |
+  </Tab>
+
+  <Tab title="Sessions">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `sessions:read` | `GET /sessions` | List sessions |
+    | `sessions:read` | `GET /sessions/*` | View a session |
+    | `sessions:write` | `POST /sessions` | Create a session |
+    | `sessions:write` | `POST /sessions/*/rename` | Rename a session |
+    | `sessions:write` | `PATCH /sessions/*` | Update a session |
+    | `sessions:delete` | `DELETE /sessions` | Delete sessions in bulk |
+    | `sessions:delete` | `DELETE /sessions/*` | Delete a session |
+  </Tab>
+
+  <Tab title="Memories">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `memories:read` | `GET /memories` | List memories |
+    | `memories:read` | `GET /memories/*` | View a memory |
+    | `memories:read` | `GET /memory_topics` | List memory topics |
+    | `memories:read` | `GET /user_memory_stats` | View user memory stats |
+    | `memories:write` | `POST /memories` | Create a memory |
+    | `memories:write` | `PATCH /memories/*` | Update a memory |
+    | `memories:write` | `POST /optimize-memories` | Optimize memories |
+    | `memories:delete` | `DELETE /memories` | Delete memories in bulk |
+    | `memories:delete` | `DELETE /memories/*` | Delete a memory |
+  </Tab>
+
+  <Tab title="Knowledge">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `knowledge:read` | `GET /knowledge/content` | List knowledge content |
+    | `knowledge:read` | `GET /knowledge/content/*` | View knowledge content |
+    | `knowledge:read` | `GET /knowledge/config` | View knowledge config |
+    | `knowledge:read` | `GET /knowledge/*/sources` | List knowledge sources |
+    | `knowledge:read` | `GET /knowledge/*/sources/*/files` | List files in a source |
+    | `knowledge:read` | `POST /knowledge/search` | Search knowledge |
+    | `knowledge:write` | `POST /knowledge/content` | Add knowledge content |
+    | `knowledge:write` | `POST /knowledge/remote-content` | Add remote knowledge content |
+    | `knowledge:write` | `PATCH /knowledge/content/*` | Update knowledge content |
+    | `knowledge:delete` | `DELETE /knowledge/content` | Delete knowledge content in bulk |
+    | `knowledge:delete` | `DELETE /knowledge/content/*` | Delete knowledge content |
+  </Tab>
+
+  <Tab title="Metrics">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `metrics:read` | `GET /metrics` | View metrics |
+    | `metrics:write` | `POST /metrics/refresh` | Refresh metrics |
+  </Tab>
+
+  <Tab title="Evals">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `evals:read` | `GET /eval-runs` | List eval runs |
+    | `evals:read` | `GET /eval-runs/*` | View an eval run |
+    | `evals:write` | `POST /eval-runs` | Create an eval run |
+    | `evals:write` | `PATCH /eval-runs/*` | Update an eval run |
+    | `evals:delete` | `DELETE /eval-runs` | Delete eval runs in bulk |
+  </Tab>
+
+  <Tab title="Traces">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `traces:read` | `GET /traces` | List traces |
+    | `traces:read` | `GET /traces/*` | View a trace |
+    | `traces:read` | `GET /trace_session_stats` | View trace session stats |
+    | `traces:read` | `POST /traces/search` | Search traces |
+  </Tab>
+
+  <Tab title="Schedules">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `schedules:read` | `GET /schedules` | List schedules |
+    | `schedules:read` | `GET /schedules/*` | View a schedule |
+    | `schedules:read` | `GET /schedules/*/runs` | List schedule runs |
+    | `schedules:read` | `GET /schedules/*/runs/*` | View a schedule run |
+    | `schedules:write` | `POST /schedules` | Create a schedule |
+    | `schedules:write` | `PATCH /schedules/*` | Update a schedule |
+    | `schedules:write` | `POST /schedules/*/enable` | Enable a schedule |
+    | `schedules:write` | `POST /schedules/*/disable` | Disable a schedule |
+    | `schedules:write` | `POST /schedules/*/trigger` | Trigger a schedule |
+    | `schedules:delete` | `DELETE /schedules/*` | Delete a schedule |
+  </Tab>
+
+  <Tab title="Approvals">
+    | Scope | Endpoint | Description |
+    |-------|----------|-------------|
+    | `approvals:read` | `GET /approvals` | List approval requests |
+    | `approvals:read` | `GET /approvals/count` | Count approval requests |
+    | `approvals:read` | `GET /approvals/*` | View an approval request |
+    | `approvals:read` | `GET /approvals/*/status` | View approval status |
+    | `approvals:write` | `POST /approvals/*/resolve` | Resolve an approval request |
+    | `approvals:delete` | `DELETE /approvals/*` | Delete an approval request |
+  </Tab>
+</Tabs>
+
+## Access Prerequisites
+
+A few scopes gate access in the control plane. 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) |
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| Bundle scopes into roles | [Roles](/agent-os/security/authorization/roles) |
+| Override scope-to-endpoint mappings | [Customization](/agent-os/security/authorization/customization) |
diff --git a/agent-os/security/authorization/self-hosted.mdx b/agent-os/security/authorization/self-hosted.mdx
new file mode 100644
index 000000000..610255d71
--- /dev/null
+++ b/agent-os/security/authorization/self-hosted.mdx
@@ -0,0 +1,151 @@
+---
+title: "Self-Hosted (BYO Token)"
+sidebarTitle: "Self-Hosted (BYO Token)"
+description: "Run AgentOS without the AgentOS control plane by issuing and verifying your own JWTs."
+---
+
+AgentOS verifies any JWT signed with a key you provide. The AgentOS control plane is one issuer; you can also issue your own tokens, or accept tokens from third-party identity providers.
+
+## Issuance Models
+
+| Model | Tokens minted by | Verification key | When to use |
+|-------|------------------|------------------|-------------|
+| Control plane | `os.agno.com` | Public key from the control plane | Default. Works with the AgentOS UI out of the box. |
+| Self-hosted | Your backend or identity provider | The key you sign with | Air-gapped, on-prem, or full control over claims. |
+
+## Issuing Your Own Tokens
+
+Sign tokens in your backend with the matching verification key. Asymmetric algorithms (RS256, ES256) use a public key. Symmetric algorithms (HS256) use a shared secret. See [Algorithm Options](/reference/agent-os/authorization-config#algorithm-options) for the full list.
+
+Tokens must include the claims from [Token Structure](/agent-os/security/authorization/tokens#token-structure). The `scopes` claim controls what the caller can do.
+
+Configure AgentOS with the verification key:
+
+```python
+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-public-key-or-shared-secret"],
+        algorithm="RS256",  # or "HS256" for shared secret
+    ),
+)
+```
+
+Send the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agents
+```
+
+See the [Basic Authorization (Symmetric)](/agent-os/usage/rbac/basic-symmetric) and [Basic Authorization (Asymmetric)](/agent-os/usage/rbac/basic-asymmetric) examples for generating signed tokens end to end.
+
+<Note>
+For key rotation, use a JWKS file instead of a single verification key. AgentOS matches the JWT's `kid` header to the right key in the file. See [Configuration Options](/agent-os/security/authorization/quickstart#configuration-options) for the `jwks_file` setup.
+</Note>
+
+## Third-Party Identity Providers
+
+AgentOS works with any standards-compliant identity provider, including WorkOS, Auth0, Okta, Clerk, Supabase, Firebase, AWS Cognito, and Keycloak. There are no provider-specific integrations to install. The setup is the same for all of them:
+
+1. Get the provider's JWKS file. Most managed IDPs expose this at a JWKS endpoint.
+2. Configure it on the JWT middleware as `jwks_file` with the matching `algorithm` (RS256 for most IDPs).
+3. Point the JWT middleware at the claim that carries permissions (`scopes_claim`), or use [custom scope mappings](/agent-os/security/authorization/customization) to define endpoint requirements in the provider's naming.
+
+<Note>
+JWKS replaces `verification_keys`; they're alternative key sources, not stacked. If the provider gives you a raw public key (PEM) instead of a JWKS endpoint, use `verification_keys=[pem]` and skip `jwks_file`.
+</Note>
+
+### Example: WorkOS
+
+Download the JWKS file from your WorkOS environment:
+
+```bash
+curl https://api.workos.com/sso/jwks/$WORKOS_CLIENT_ID > workos-jwks.json
+```
+
+Point AgentOS at it. WorkOS tokens carry permissions under the `permissions` claim, so set `scopes_claim="permissions"` on the JWT middleware:
+
+```python
+from agno.os import AgentOS
+from agno.os.middleware.jwt import JWTMiddleware
+
+agent_os = AgentOS(
+    id="my-agent-os",
+    agents=[agent],
+)
+
+app = agent_os.get_app()
+
+app.add_middleware(
+    JWTMiddleware,
+    jwks_file="workos-jwks.json",
+    algorithm="RS256",
+    scopes_claim="permissions",
+    authorization=True,
+)
+```
+
+WorkOS access tokens carry `permissions`, `role`, `org_id`, and `sid` claims by default. If your WorkOS permission names already match AgentOS scopes (e.g., `agents:read`), the middleware passes them through directly. If they don't, use [custom scope mappings](/agent-os/security/authorization/customization) to redefine endpoint requirements in WorkOS's naming.
+
+<Note>
+**Why this example uses `JWTMiddleware` instead of `AuthorizationConfig`.** `AuthorizationConfig` covers verification keys, algorithm, audience, and isolation, but not claim names or token sources. Use it when the provider's JWT uses the standard `scopes` and `sub` claims. For providers that use a different claim name (WorkOS `permissions`, Auth0 `scope`, Okta `scp`), or when you need cookie tokens or custom scope mappings, use `JWTMiddleware` directly.
+</Note>
+
+See [WorkOS BYOT](/agent-os/usage/rbac/workos-byot) for a runnable example.
+
+## Accepting Multiple Issuers
+
+`verification_keys` is a list. AgentOS tries each key in order until one verifies the token. Pass a second key to accept tokens from both the AgentOS control plane and your own backend at the same time.
+
+```python
+authorization_config=AuthorizationConfig(
+    verification_keys=[
+        AGENTOS_CONTROL_PLANE_PUBLIC_KEY,  # tokens issued by os.agno.com
+        YOUR_BACKEND_PUBLIC_KEY,        # tokens minted by your service
+    ],
+    algorithm="RS256",
+)
+```
+
+This keeps the AgentOS UI working through the control plane while your backend mints its own tokens for service-to-service or production traffic. All keys in the list must use the algorithm set in `algorithm`.
+
+<Note>
+For a mix of JWKS-based and raw-key issuers (e.g., a third-party IDP plus the AgentOS control plane), set both `jwks_file` and `verification_keys`. AgentOS tries JWKS keys first (matched by `kid`), then static verification keys as a fallback.
+</Note>
+
+<Note>
+Order matters for performance, not correctness. AgentOS tries each key in order and stops at the first match. Put the most common issuer first to skip an extra decode attempt per request.
+</Note>
+
+## Reading Tokens from Cookies
+
+By default, AgentOS reads the JWT from the `Authorization: Bearer` header. For browser apps that hit AgentOS directly, use the JWT middleware to read from a cookie, or both.
+
+```python
+from agno.os.middleware.jwt import JWTMiddleware, TokenSource
+
+app = agent_os.get_app()
+
+app.add_middleware(
+    JWTMiddleware,
+    verification_keys=["your-public-key"],
+    algorithm="RS256",
+    token_source=TokenSource.BOTH,   # HEADER | COOKIE | BOTH
+    cookie_name="access_token",
+)
+```
+
+See [JWT Middleware](/agent-os/middleware/jwt#token-sources) for the full set of token-source options.
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| See claim structure and example tokens | [Tokens](/agent-os/security/authorization/tokens) |
+| See the full scope reference | [Scopes](/agent-os/security/authorization/scopes) |
+| Configure JWT middleware in depth | [JWT Middleware](/agent-os/middleware/jwt) |
diff --git a/agent-os/security/authorization/tokens.mdx b/agent-os/security/authorization/tokens.mdx
new file mode 100644
index 000000000..96a5dfd94
--- /dev/null
+++ b/agent-os/security/authorization/tokens.mdx
@@ -0,0 +1,73 @@
+---
+title: "JSON Web Tokens (JWT)"
+sidebarTitle: "JSON Web Tokens (JWT)"
+description: "JWT claim structure, example tokens, and how AgentOS reads them."
+---
+
+AgentOS reads the JWT from the `Authorization: Bearer <token>` header on every request. Tokens can come from the AgentOS control plane or your own backend.
+
+## Token Structure
+
+Your JWT tokens should include:
+
+```json
+{
+  "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`) |
+| `exp` | No | Expiry timestamp. Recommended; expired tokens are rejected. |
+| `iat` | No | Issued-at timestamp. |
+
+## Example Tokens
+
+**Read-only access:**
+
+```json
+{
+  "scopes": ["agents:read", "teams:read", "sessions:read"]
+}
+```
+
+**Run a specific agent:**
+
+```json
+{
+  "scopes": ["agents:my-agent:run", "agents:my-agent:read", "sessions:write"]
+}
+```
+
+**Admin access:**
+
+```json
+{
+  "scopes": ["agent_os:admin"]
+}
+```
+
+See [Scopes](/agent-os/security/authorization/scopes) for the full list.
+
+## Sending Tokens
+
+Send the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agents
+```
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| Issue tokens from your own backend | [Self-Hosted](/agent-os/security/authorization/self-hosted) |
+| See the full scope reference | [Scopes](/agent-os/security/authorization/scopes) |
+| Configure JWT middleware directly | [JWT Middleware](/agent-os/middleware/jwt) |
diff --git a/agent-os/security/authorization/user-isolation.mdx b/agent-os/security/authorization/user-isolation.mdx
new file mode 100644
index 000000000..5eef8960b
--- /dev/null
+++ b/agent-os/security/authorization/user-isolation.mdx
@@ -0,0 +1,45 @@
+---
+title: "Per-User Data Isolation"
+sidebarTitle: "User Isolation"
+description: "Scope sessions, memories, and traces to the caller's user ID."
+---
+
+Authorization controls which operations a caller can perform. Per-user data isolation controls which rows a caller can see and write. Opt in with `user_isolation=True`:
+
+```python
+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",
+        user_isolation=True,
+    ),
+)
+```
+
+When enabled, AgentOS uses the JWT `sub` claim as the `user_id` for every non-admin caller:
+
+| Operation | Behavior with `user_isolation=True` |
+|-----------|-------------------------------------|
+| Reads (sessions, memory, traces) | Scoped to the caller's `user_id`. Other users' rows are not returned. |
+| Writes (sessions, memories, traces) | `user_id` is coerced to the caller's `sub`. A caller cannot persist rows attributed to another user. |
+| Cancel / resume / continue routes | Require `session_id` and verify the caller owns the run. |
+| WebSocket reconnect | Requires `session_id` (and `workflow_id`) for non-admins. |
+
+A caller holding `admin_scope` (default `agent_os:admin`) bypasses isolation and sees all data. Set a custom override with `admin_scope="ops:admin"`.
+
+<Note>
+Isolation is off by default. JWT and scope checks still apply when `user_isolation=False`, but routes operate on the unscoped database and add no per-user ownership gates on top of authorization. Per-user isolation requires a database that records `user_id` (PostgreSQL recommended for production).
+</Note>
+
+## Next Steps
+
+| Task | Guide |
+|------|-------|
+| Issue tokens with the `sub` claim | [Tokens](/agent-os/security/authorization/tokens) |
+| See the user isolation cookbook example | [user_isolation.py](https://github.com/agno-agi/agno/blob/main/cookbook/05_agent_os/rbac/symmetric/user_isolation.py) |
diff --git a/agent-os/security/overview.mdx b/agent-os/security/overview.mdx
index c1b1ef597..329794ea5 100644
--- a/agent-os/security/overview.mdx
+++ b/agent-os/security/overview.mdx
@@ -4,12 +4,12 @@ sidebarTitle: "Overview"
 description: "Secure your AgentOS with authentication and authorization."
 ---
 
-AgentOS supports two security mechanisms:
+AgentOS supports two security modes:
 
-| Method | Use Case |
-|--------|----------|
-| **Basic Authentication** | Simple key validation for development |
-| **RBAC** | JWT-powered authorization with fine-grained scopes for production |
+| Mode | When to use |
+|------|-------------|
+| **Basic Authentication** | Simple key validation for development. |
+| **Authorization** | 	JWT-powered authorization with fine-grained scopes for production. |
 
 ## Basic Authentication
 
@@ -20,9 +20,9 @@ export OS_SECURITY_KEY="your-secret-key"
 
 Requests without a valid `Authorization: Bearer <key>` header return `401 Unauthorized`.
 
-## Role-Based Access Control (RBAC)
+## Authorization
 
-RBAC validates JWT tokens and checks scopes against required permissions for each endpoint. Enable it with `authorization=True`:
+Authorization validates JWT tokens and checks scopes against required permissions for each endpoint. Enable it with `authorization=True`:
 ```python
 from agno.os import AgentOS
 
@@ -40,21 +40,21 @@ export JWT_VERIFICATION_KEY="your-public-key"
 
 Requests without a valid JWT return `401 Unauthorized`. Requests with insufficient scopes return `403 Forbidden`.
 
-See the [RBAC documentation](/agent-os/security/rbac) for the full setup flow, scope reference, and endpoint mappings.
+See [Authorization](/agent-os/security/authorization/overview) for the full setup flow, scope reference, and endpoint mappings.
 
 <CardGroup cols={2}>
   <Card
-    title="RBAC Documentation"
+    title="Authorization"
     icon="lock"
-    href="/agent-os/security/rbac"
+    href="/agent-os/security/authorization/overview"
   >
-    Complete scopes, permissions, and access control configuration.
+    JWT validation, scopes, roles, and per-user data isolation.
   </Card>
   <Card
     title="JWT Middleware"
     icon="key"
     href="/agent-os/middleware/jwt"
   >
-    JWT authentication with parameter injection and claims extraction.
+    Token sources, claim extraction, and parameter injection.
   </Card>
 </CardGroup>
\ No newline at end of file
diff --git a/agent-os/security/rbac.mdx b/agent-os/security/rbac.mdx
deleted file mode 100644
index 792236320..000000000
--- a/agent-os/security/rbac.mdx
+++ /dev/null
@@ -1,594 +0,0 @@
----
-title: "Role-Based Access Control (RBAC)"
-sidebarTitle: "RBAC"
-description: "Secure your AgentOS with fine-grained permissions."
----
-
-AgentOS validates the JWT on every request, then checks its scopes against the permissions each endpoint requires. This controls who can access and run your agents, teams, and workflows.
-
-<img
-  className="block dark:hidden"
-  src="/images/jwt-verification-light.png"
-  alt="JWT verification flow"
-/>
-
-<img
-  className="hidden dark:block"
-  src="/images/jwt-verification-dark.png"
-  alt="JWT verification flow"
-/>
-
-## Quick Start
-
-Enable RBAC when initializing AgentOS:
-```python
-from agno.agent import Agent
-from agno.models.openai import OpenAIResponses
-from agno.os import AgentOS
-
-
-agent = Agent(
-    id="my-agent",
-    model=OpenAIResponses(id="gpt-5.2"),
-)
-
-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 authorization. To verify tokens, AgentOS also needs a public key. Generate one from the control plane and wire it in.
-
-<Steps>
-  <Step title="Toggle JWT authorization">
-    Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.
-  </Step>
-
-  <Step title="Copy the public key">
-    Copy the public key for your AgentOS from the modal
-  </Step>
-
-  <Step title="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:
-    ```bash
-    export JWT_VERIFICATION_KEY="your-public-key"
-    ```
-
-    Or, if you manage keys via a JWKS file, point AgentOS at it instead:
-    ```bash
-    export JWT_JWKS_FILE="/path/to/jwks.json"
-    ```
-  </Step>
-</Steps>
-
-Authorization is now active for your AgentOS.
-
-<Note>
-The control plane only issues **RS256** keys, which is also the default. See [authorization troubleshooting](/faq/rbac-auth-failed) for common setup issues.
-</Note>
-
-<video
-  autoPlay
-  muted
-  controls
-  className="w-full aspect-video"
-  src="/videos/auth-on-connect-web.mp4"
-></video>
-
-## Configuration Options
-
-Configure JWT verification using `AuthorizationConfig`:
-```python
-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:
-```python
-authorization_config=AuthorizationConfig(
-    jwks_file="/path/to/jwks.json",
-    algorithm="RS256",
-)
-```
-
-Or set environment variables:
-```bash
-export JWT_VERIFICATION_KEY="your-public-key"
-# or
-export JWT_JWKS_FILE="/path/to/jwks.json"
-```
-
-## Running AgentOS Independently
-
-The control plane is one way to issue verification keys, not the only way. AgentOS verifies any JWT signed with a key you provide, so you can mint and verify tokens entirely on your own infrastructure.
-
-### Issuing tokens
-
-AgentOS verifies tokens but doesn't issue them. Generate them in your backend or identity provider, signed with the key whose public half or shared secret you set as a verification key. Include the claims from [JWT Token Structure](#jwt-token-structure); `scopes` is the claim RBAC checks.
-
-Send the token in the `Authorization` header:
-
-```bash
-curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agents
-```
-
-See the [Basic RBAC (Symmetric)](/agent-os/usage/rbac/basic-symmetric) and [Basic RBAC (Asymmetric)](/agent-os/usage/rbac/basic-asymmetric) examples for generating signed tokens end to end.
-
-### Accepting multiple issuers
-
-`verification_keys` is a list. AgentOS tries each key in order until one verifies the token. Pass a second key to accept tokens from both the Agno control plane and your own backend at the same time.
-
-```python
-authorization_config=AuthorizationConfig(
-    verification_keys=[
-        AGNO_CONTROL_PLANE_PUBLIC_KEY,  # tokens issued by os.agno.com
-        YOUR_BACKEND_PUBLIC_KEY,        # tokens minted by your service
-    ],
-    algorithm="RS256",
-)
-```
-
-This keeps the AgentOS UI working through the control plane while your backend mints its own tokens for service-to-service or production traffic. All keys in the list must use the algorithm set in `algorithm`.
-
-## JWT Token Structure
-
-Your JWT tokens should include:
-```json
-{
-  "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`) |
-| `exp` | No | Expiry timestamp. Recommended; expired tokens are rejected. |
-| `iat` | No | Issued-at timestamp. |
-
-### Example Tokens
-
-**Read-only access:**
-```json
-{
-  "scopes": ["agents:read", "teams:read", "sessions:read"]
-}
-```
-
-**Run a specific agent:**
-```json
-{
-  "scopes": ["agents:my-agent:run", "agents:my-agent:read", "sessions:write"]
-}
-```
-
-**Admin access:**
-```json
-{
-  "scopes": ["agent_os:admin"]
-}
-```
-
-## 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 |
-
-
-## Scope Reference
-
-Scopes split across two enforcement layers. Platform scopes are checked by the control plane. AgentOS scopes are checked by your runtime against incoming requests.
-
-Any `resource:action` scope also accepts a `resource:<id>:action` form to limit access to a specific resource. See [Scope Format](#scope-format).
-
-The `agent_os:admin` scope grants full access to every AgentOS endpoint below.
-
-### Platform Scopes
-
-| 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 |
-| `org:write` | Update organization details |
-| `org:delete` | Delete the organization |
-| `org:members:read` | View organization members |
-| `org:members:write` | Invite and update organization members |
-| `org:roles:read` | View organization roles and their scope assignments |
-| `org:roles:write` | Create and update organization role scopes |
-| `org:roles:delete` | Delete organization roles |
-| `billing:read` | View billing details and invoices |
-| `billing:write` | Update billing settings and payment methods |
-
-### AgentOS Scopes
-
-<Tabs>
-  <Tab title="Config">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `config:read` | `GET /config` | Read the OS configuration |
-    | `config:read` | `GET /models` | List available models |
-    | `config:write` | `POST /databases/all/migrate` | Run migrations on all databases |
-    | `config:write` | `POST /databases/*/migrate` | Run migrations on a specific database |
-  </Tab>
-
-  <Tab title="Registry">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `registry:read` | `GET /registry` | View the code-defined registry (tools, models, databases) |
-  </Tab>
-
-  <Tab title="Components">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `components:read` | `GET /components` | List components |
-    | `components:read` | `GET /components/*` | View a component |
-    | `components:read` | `GET /components/*/configs` | List a component's configs |
-    | `components:read` | `GET /components/*/configs/*` | View a component config |
-    | `components:read` | `GET /components/*/configs/current` | View the current component config |
-    | `components:write` | `POST /components` | Create a component |
-    | `components:write` | `POST /components/*/configs` | Create a component config |
-    | `components:write` | `POST /components/*/configs/*/set-current` | Mark a config as current |
-    | `components:write` | `PATCH /components/*` | Update a component |
-    | `components:write` | `PATCH /components/*/configs/*` | Update a component config |
-    | `components:delete` | `DELETE /components/*` | Delete a component |
-    | `components:delete` | `DELETE /components/*/configs/*` | Delete a component config |
-  </Tab>
-
-  <Tab title="Agents">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `agents:read` | `GET /agents` | List agents |
-    | `agents:read` | `GET /agents/*` | View an agent |
-    | `agents:write` | `POST /agents` | Create an agent |
-    | `agents:write` | `PATCH /agents/*` | Update an agent |
-    | `agents:delete` | `DELETE /agents/*` | Delete an agent |
-    | `agents:run` | `POST /agents/*/runs` | Run an agent |
-    | `agents:run` | `POST /agents/*/runs/*/continue` | Continue a paused run |
-    | `agents:run` | `POST /agents/*/runs/*/cancel` | Cancel a run |
-  </Tab>
-
-  <Tab title="Teams">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `teams:read` | `GET /teams` | List teams |
-    | `teams:read` | `GET /teams/*` | View a team |
-    | `teams:write` | `POST /teams` | Create a team |
-    | `teams:write` | `PATCH /teams/*` | Update a team |
-    | `teams:delete` | `DELETE /teams/*` | Delete a team |
-    | `teams:run` | `POST /teams/*/runs` | Run a team |
-    | `teams:run` | `POST /teams/*/runs/*/continue` | Continue a paused run |
-    | `teams:run` | `POST /teams/*/runs/*/cancel` | Cancel a run |
-  </Tab>
-
-  <Tab title="Workflows">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `workflows:read` | `GET /workflows` | List workflows |
-    | `workflows:read` | `GET /workflows/*` | View a workflow |
-    | `workflows:write` | `POST /workflows` | Create a workflow |
-    | `workflows:write` | `PATCH /workflows/*` | Update a workflow |
-    | `workflows:delete` | `DELETE /workflows/*` | Delete a workflow |
-    | `workflows:run` | `POST /workflows/*/runs` | Run a workflow |
-    | `workflows:run` | `POST /workflows/*/runs/*/continue` | Continue a paused run |
-    | `workflows:run` | `POST /workflows/*/runs/*/cancel` | Cancel a run |
-  </Tab>
-
-  <Tab title="Sessions">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `sessions:read` | `GET /sessions` | List sessions |
-    | `sessions:read` | `GET /sessions/*` | View a session |
-    | `sessions:write` | `POST /sessions` | Create a session |
-    | `sessions:write` | `POST /sessions/*/rename` | Rename a session |
-    | `sessions:write` | `PATCH /sessions/*` | Update a session |
-    | `sessions:delete` | `DELETE /sessions` | Delete sessions in bulk |
-    | `sessions:delete` | `DELETE /sessions/*` | Delete a session |
-  </Tab>
-
-  <Tab title="Memories">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `memories:read` | `GET /memories` | List memories |
-    | `memories:read` | `GET /memories/*` | View a memory |
-    | `memories:read` | `GET /memory_topics` | List memory topics |
-    | `memories:read` | `GET /user_memory_stats` | View user memory stats |
-    | `memories:write` | `POST /memories` | Create a memory |
-    | `memories:write` | `PATCH /memories/*` | Update a memory |
-    | `memories:write` | `POST /optimize-memories` | Optimize memories |
-    | `memories:delete` | `DELETE /memories` | Delete memories in bulk |
-    | `memories:delete` | `DELETE /memories/*` | Delete a memory |
-  </Tab>
-
-  <Tab title="Knowledge">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `knowledge:read` | `GET /knowledge/content` | List knowledge content |
-    | `knowledge:read` | `GET /knowledge/content/*` | View knowledge content |
-    | `knowledge:read` | `GET /knowledge/config` | View knowledge config |
-    | `knowledge:read` | `GET /knowledge/*/sources` | List knowledge sources |
-    | `knowledge:read` | `GET /knowledge/*/sources/*/files` | List files in a source |
-    | `knowledge:read` | `POST /knowledge/search` | Search knowledge |
-    | `knowledge:write` | `POST /knowledge/content` | Add knowledge content |
-    | `knowledge:write` | `POST /knowledge/remote-content` | Add remote knowledge content |
-    | `knowledge:write` | `PATCH /knowledge/content/*` | Update knowledge content |
-    | `knowledge:delete` | `DELETE /knowledge/content` | Delete knowledge content in bulk |
-    | `knowledge:delete` | `DELETE /knowledge/content/*` | Delete knowledge content |
-  </Tab>
-
-  <Tab title="Metrics">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `metrics:read` | `GET /metrics` | View metrics |
-    | `metrics:write` | `POST /metrics/refresh` | Refresh metrics |
-  </Tab>
-
-  <Tab title="Evals">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `evals:read` | `GET /eval-runs` | List eval runs |
-    | `evals:read` | `GET /eval-runs/*` | View an eval run |
-    | `evals:write` | `POST /eval-runs` | Create an eval run |
-    | `evals:write` | `PATCH /eval-runs/*` | Update an eval run |
-    | `evals:delete` | `DELETE /eval-runs` | Delete eval runs in bulk |
-  </Tab>
-
-  <Tab title="Traces">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `traces:read` | `GET /traces` | List traces |
-    | `traces:read` | `GET /traces/*` | View a trace |
-    | `traces:read` | `GET /trace_session_stats` | View trace session stats |
-    | `traces:read` | `POST /traces/search` | Search traces |
-  </Tab>
-
-  <Tab title="Schedules">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `schedules:read` | `GET /schedules` | List schedules |
-    | `schedules:read` | `GET /schedules/*` | View a schedule |
-    | `schedules:read` | `GET /schedules/*/runs` | List schedule runs |
-    | `schedules:read` | `GET /schedules/*/runs/*` | View a schedule run |
-    | `schedules:write` | `POST /schedules` | Create a schedule |
-    | `schedules:write` | `PATCH /schedules/*` | Update a schedule |
-    | `schedules:write` | `POST /schedules/*/enable` | Enable a schedule |
-    | `schedules:write` | `POST /schedules/*/disable` | Disable a schedule |
-    | `schedules:write` | `POST /schedules/*/trigger` | Trigger a schedule |
-    | `schedules:delete` | `DELETE /schedules/*` | Delete a schedule |
-  </Tab>
-
-  <Tab title="Approvals">
-    | Scope | Endpoint | Description |
-    |-------|----------|-------------|
-    | `approvals:read` | `GET /approvals` | List approval requests |
-    | `approvals:read` | `GET /approvals/count` | Count approval requests |
-    | `approvals:read` | `GET /approvals/*` | View an approval request |
-    | `approvals:read` | `GET /approvals/*/status` | View approval status |
-    | `approvals:write` | `POST /approvals/*/resolve` | Resolve an approval request |
-    | `approvals:delete` | `DELETE /approvals/*` | Delete an approval request |
-  </Tab>
-</Tabs>
-
-## Access Prerequisites
-
-A few scopes gate access in the platform. 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) |
-
-
-
-## Default Roles
-
-Every organization comes with three default roles.
-
-| Capability                          | Owner | Administrator | Member |
-|-------------------------------------|:-----:|:-------------:|:------:|
-| Run agents, teams, workflows        |   ✓   |       ✓       |   ✓    |
-| Create and update AgentOS resources |   ✓   |       ✓       |   ✓    |
-| Delete AgentOS resources            |   ✓   |       ✓       |        |
-| Create and update AgentOS instances |   ✓   |       ✓       |   ✓    |
-| Delete AgentOS instances            |   ✓   |               |        |
-| Manage members and roles            |   ✓   |       ✓       |        |
-| Update organization settings        |   ✓   |       ✓       |        |
-| View billing                        |   ✓   |       ✓       |   ✓    |
-| Update billing                      |   ✓   |               |        |
-| Delete the organization             |   ✓   |               |        |
-
-## Custom Roles and Scopes
-
-<Note>
-Custom roles and scopes are available on the Enterprise plan. [Book a call](https://cal.com/team/agno/intro) or email [support@agno.com](mailto:support@agno.com) to enable.
-</Note>
-
-<Warning>
-Custom roles require JWT authentication. Without it, scope enforcement is skipped entirely by AgentOS and assigned roles have no effect.
-</Warning>
-
-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
-
-1. Open the [Roles page](https://os.agno.com/settings/roles) in the control plane.
-2. Define a role name and select the scopes it grants.
-3. Save the role.
-
-### Assign a Role to a User
-
-Open the [Organization settings page](https://os.agno.com/settings/organization) and assign the role to a user.
-
-<video
-  autoPlay
-  muted
-  controls
-  className="w-full aspect-video"
-  src="/videos/roles.mp4"
-></video>
-## Custom Scope Mappings
-
-Customize or extend the default scope mappings using the JWT middleware:
-```python
-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.
-
-## Per-User Data Isolation
-
-RBAC controls which operations a caller can perform. Per-user data isolation controls which rows a caller can see and write. Opt in with `user_isolation=True`:
-
-```python
-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",
-        user_isolation=True,
-    ),
-)
-```
-
-When enabled, AgentOS uses the JWT `sub` claim as the `user_id` for every non-admin caller:
-
-| Operation | Behavior with `user_isolation=True` |
-|-----------|-------------------------------------|
-| Reads (sessions, memory, traces) | Scoped to the caller's `user_id`. Other users' rows are not returned. |
-| Writes (sessions, memories, traces) | `user_id` is coerced to the caller's `sub`. A caller cannot persist rows attributed to another user. |
-| Cancel / resume / continue routes | Require `session_id` and verify the caller owns the run. |
-| WebSocket reconnect | Requires `session_id` (and `workflow_id`) for non-admins. |
-
-A caller holding `admin_scope` (default `agent_os:admin`) bypasses isolation and sees all data. Set a custom override with `admin_scope="ops:admin"`.
-
-<Note>
-Isolation is off by default. JWT/RBAC still apply when `user_isolation=False`, but routes operate on the unscoped database and add no per-user ownership gates on top of RBAC. Per-user isolation requires a database that records `user_id` (PostgreSQL recommended for production).
-</Note>
-
-## Excluded Routes
-
-These routes are excluded from RBAC checks by default:
-
-`/`, `/health`, `/info`, `/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 |
-
-## Examples
-
-<CardGroup cols={2}>
-  <Card
-    title="Basic RBAC (Symmetric)"
-    icon="lock"
-    href="/agent-os/usage/rbac/basic-symmetric"
-  >
-    Enable RBAC with a shared-secret JWT (HS256)
-  </Card>
-  <Card
-    title="Basic RBAC (Asymmetric)"
-    icon="key"
-    href="/agent-os/usage/rbac/basic-asymmetric"
-  >
-    Sign with a private key, verify with the public key (RS256)
-  </Card>
-  <Card
-    title="Per-Agent Permissions"
-    icon="user"
-    href="/agent-os/usage/rbac/per-agent-permissions"
-  >
-    Grant specific permissions to specific agents
-  </Card>
-  <Card
-    title="Per-User Data Isolation"
-    icon="users"
-    href="https://github.com/agno-agi/agno/blob/main/cookbook/05_agent_os/rbac/symmetric/user_isolation.py"
-  >
-    Scope sessions, memory, and traces per user with user_isolation=True
-  </Card>
-</CardGroup>
-
-## Developer Resources
-
-<CardGroup cols={2}>
-  <Card
-    title="JWT Middleware"
-    icon="key"
-    href="/agent-os/middleware/jwt"
-  >
-    Configure token sources, claim extraction, and scope checking
-  </Card>
-  <Card
-    title="AuthorizationConfig Reference"
-    icon="gear"
-    href="/reference/agent-os/authorization-config"
-  >
-    Configuration options for JWT verification
-  </Card>
-  <Card
-    title="JWTMiddleware Reference"
-    icon="code"
-    href="/reference/agent-os/jwt-middleware"
-  >
-    Complete JWT middleware class reference
-  </Card>
-</CardGroup>
\ No newline at end of file
diff --git a/agent-os/usage/rbac/workos-byot.mdx b/agent-os/usage/rbac/workos-byot.mdx
new file mode 100644
index 000000000..9fbdc80a6
--- /dev/null
+++ b/agent-os/usage/rbac/workos-byot.mdx
@@ -0,0 +1,258 @@
+---
+title: WorkOS BYOT (Bring Your Own Token)
+sidebarTitle: WorkOS BYOT
+---
+
+Use WorkOS as the JWT issuer for AgentOS. WorkOS signs tokens with its keys; AgentOS verifies them against the WorkOS JWKS and reads scopes from the `permissions` claim.
+
+This example provisions everything via the WorkOS API: permissions, three roles (`admin`, `member`, `viewer`), one organization, and three users. It mints a real WorkOS-signed access token per user and prints a curl command for each.
+
+<Steps>
+
+  <Step title="Create a Python file">
+    ```python workos_byot.py
+    """
+    WorkOS BYOT with AgentOS - 3 roles, real WorkOS tokens, RBAC provisioned via API.
+
+    Roles (permission slugs match AgentOS scopes):
+    - admin  -> agent_os:admin                          (full access)
+    - member -> agents:read, agents:run, sessions:read  (can list/run agents)
+    - viewer -> sessions:read                           (no agents:read -> 403 on /agents)
+
+    One-time WorkOS dashboard prerequisites:
+    - Enable RBAC (so permissions/roles can be created).
+    - Enable Email + Password authentication (so the password grant works).
+    """
+
+    import os
+
+    import httpx
+    import jwt
+    from agno.agent import Agent
+    from agno.db.sqlite import SqliteDb
+    from agno.models.openai import OpenAIResponses
+    from agno.os import AgentOS
+    from agno.os.middleware.jwt import JWTMiddleware
+    from workos import WorkOSClient
+    from workos.organization_membership._resource import RoleSingle
+    from workos.user_management import PasswordPlaintext
+
+
+    def _env(name: str) -> str | None:
+        value = os.getenv(name)
+        return value.strip().strip("\"'").strip() if value else None
+
+
+    WORKOS_CLIENT_ID = _env("WORKOS_CLIENT_ID")
+    WORKOS_API_KEY = _env("WORKOS_API_KEY")
+    if not WORKOS_CLIENT_ID or not WORKOS_API_KEY:
+        raise SystemExit(
+            "Set WORKOS_CLIENT_ID and WORKOS_API_KEY (from the same WorkOS "
+            "environment) before running."
+        )
+
+    _JWKS_FILE = "/tmp/agno_workos_jwks.json"
+
+    workos = WorkOSClient(api_key=WORKOS_API_KEY, client_id=WORKOS_CLIENT_ID)
+
+    # RBAC definition - permission slugs match AgentOS scope names.
+    ORG_NAME = "Agno BYOT Demo"
+    DEMO_DOMAIN = "agno-byot-demo.com"
+    DEMO_PASSWORD = "Agno-Demo-Passw0rd!"
+
+    PERMISSIONS = ["agents:read", "agents:run", "sessions:read", "agent_os:admin"]
+    ROLES = {
+        "admin": ["agent_os:admin"],
+        "member": ["agents:read", "agents:run", "sessions:read"],
+        "viewer": ["sessions:read"],
+    }
+    USERS = [
+        ("admin", "admin", "admin"),
+        ("member", "member", "member"),
+        ("viewer", "viewer", "viewer"),
+    ]
+
+
+    def _download_workos_jwks(client_id: str, dest: str) -> str:
+        """Fetch the public WorkOS JWKS and write it to a local file.
+        `jwks_file` requires a local path, not a URL."""
+        url = f"https://api.workos.com/sso/jwks/{client_id}"
+        response = httpx.get(url, timeout=10.0)
+        response.raise_for_status()
+        with open(dest, "w") as f:
+            f.write(response.text)
+        return dest
+
+
+    # RBAC provisioning via the WorkOS API (idempotent). Demo-only.
+    # In production, your users log in through your existing WorkOS flow; AgentOS
+    # only has to verify the token (see the JWTMiddleware setup below).
+
+    def _ensure_permissions() -> None:
+        for slug in PERMISSIONS:
+            try:
+                workos.authorization.create_permission(slug=slug, name=slug)
+            except Exception:
+                pass
+
+
+    def _ensure_roles() -> None:
+        for slug, perms in ROLES.items():
+            try:
+                workos.authorization.create_environment_role(slug=slug, name=slug)
+            except Exception:
+                pass
+            workos.authorization.set_environment_role_permissions(slug, permissions=perms)
+
+
+    def _ensure_org() -> str:
+        for org in workos.organizations.list_organizations(limit=100).data:
+            if org.name == ORG_NAME:
+                return org.id
+        return workos.organizations.create_organization(name=ORG_NAME).id
+
+
+    def _ensure_user(email: str) -> str:
+        password = PasswordPlaintext(password=DEMO_PASSWORD)
+        try:
+            return workos.user_management.create_user(
+                email=email, password=password, email_verified=True
+            ).id
+        except Exception:
+            user_id = workos.user_management.list_users(email=email).data[0].id
+            workos.user_management.update_user(user_id, password=password)
+            return user_id
+
+
+    def _ensure_membership(user_id: str, org_id: str, role_slug: str) -> None:
+        try:
+            workos.organization_membership.create_organization_membership(
+                user_id=user_id,
+                organization_id=org_id,
+                role=RoleSingle(role_slug=role_slug),
+            )
+        except Exception:
+            pass
+
+
+    def _mint_token(email: str) -> str:
+        """Mint a real WorkOS access token via the password grant.
+        Single-org users get org-scoped tokens that carry permissions."""
+        auth = workos.user_management.authenticate_with_password(
+            email=email, password=DEMO_PASSWORD
+        )
+        return auth.access_token
+
+
+    # AgentOS configured to verify WorkOS tokens via JWKS + `permissions` claim.
+    # This is the actual WorkOS integration - the only part needed in production.
+
+    _download_workos_jwks(WORKOS_CLIENT_ID, _JWKS_FILE)
+
+    db = SqliteDb(db_file="tmp/workos_byot.db")
+
+    research_agent = Agent(
+        id="research-agent",
+        name="Research Agent",
+        model=OpenAIResponses(id="gpt-5-mini"),
+        db=db,
+        add_history_to_context=True,
+        markdown=True,
+    )
+
+    # AuthorizationConfig can't set claim names. WorkOS uses `permissions`
+    # (not the default `scopes`), so JWTMiddleware is required.
+    agent_os = AgentOS(
+        id="my-agent-os",
+        description="AgentOS verifying WorkOS-issued tokens (BYOT)",
+        agents=[research_agent],
+    )
+
+    app = agent_os.get_app()
+
+    app.add_middleware(
+        JWTMiddleware,
+        jwks_file=_JWKS_FILE,
+        algorithm="RS256",
+        scopes_claim="permissions",
+        admin_scope="agent_os:admin",
+        authorization=True,
+    )
+
+
+    if __name__ == "__main__":
+        print("\n" + "=" * 70)
+        print("WorkOS BYOT - provisioning RBAC (permissions, roles, org, users)")
+        print("=" * 70)
+
+        _ensure_permissions()
+        _ensure_roles()
+        org_id = _ensure_org()
+        print("Organization: " + ORG_NAME + " (" + org_id + ")")
+
+        tokens = []
+        for label, local_part, role_slug in USERS:
+            email = f"{local_part}@{DEMO_DOMAIN}"
+            user_id = _ensure_user(email)
+            _ensure_membership(user_id, org_id, role_slug)
+            token = _mint_token(email)
+            perms = jwt.decode(token, options={"verify_signature": False}).get(
+                "permissions", []
+            )
+            tokens.append((label, role_slug, perms, token))
+            print(f"Provisioned {label:7} {email:32} role={role_slug} perms={perms}")
+
+        print("\n" + "=" * 70)
+        print("Test commands (each token signed by WorkOS, verified via JWKS)")
+        print("=" * 70)
+        for label, role_slug, perms, token in tokens:
+            print(f"\n# {label} ({role_slug}, permissions={perms}):")
+            print(
+                f'curl -i -H "Authorization: Bearer {token}" http://localhost:7777/agents'
+            )
+
+        print("\n# No token -> 401:")
+        print("curl -i http://localhost:7777/agents")
+
+        agent_os.serve(app="workos_byot:app", port=7777, reload=True)
+    ```
+  </Step>
+
+  <Snippet file="create-venv-step.mdx" />
+
+  <Step title="Install dependencies">
+    ```bash
+    uv pip install -U agno openai pyjwt workos httpx "fastapi[standard]" uvicorn sqlalchemy
+    ```
+  </Step>
+
+  <Step title="Export your credentials">
+    Both must come from the **same** WorkOS environment:
+
+    ```bash
+    export WORKOS_API_KEY="sk_..."
+    export WORKOS_CLIENT_ID="client_..."
+    export OPENAI_API_KEY="your_openai_api_key_here"
+    ```
+  </Step>
+
+  <Step title="Run the AgentOS">
+    ```bash
+    python workos_byot.py
+    ```
+
+    The script provisions RBAC in WorkOS, mints a WorkOS-signed token per user, and prints a curl command for each.
+  </Step>
+
+  <Step title="Test RBAC">
+    Run the curl commands printed by the script. Expected outcomes on `GET /agents`:
+
+    | User | Permissions | Result |
+    |------|-------------|--------|
+    | admin | `agent_os:admin` | `200 OK` |
+    | member | `agents:read`, `agents:run`, `sessions:read` | `200 OK` |
+    | viewer | `sessions:read` | `403 Forbidden` |
+    | (no token) | — | `401 Unauthorized` |
+  </Step>
+
+</Steps>
diff --git a/docs.json b/docs.json
index 4a022cf0d..a4e07dd72 100644
--- a/docs.json
+++ b/docs.json
@@ -4415,14 +4415,7 @@
               "agent-os/introduction",
               "agent-os/run-your-os",
               "agent-os/connect-your-os",
-              "agent-os/control-plane",
-              {
-                "group": "Security & Authorization",
-                "pages": [
-                  "agent-os/security/overview",
-                  "agent-os/security/rbac"
-                ]
-              }
+              "agent-os/control-plane"
             ]
           },
           {
@@ -4452,6 +4445,25 @@
                   "agent-os/middleware/jwt"
                 ]
               },
+              {
+                "group": "Security & Authorization",
+                "pages": [
+                  "agent-os/security/overview",
+                  {
+                    "group": "Authorization",
+                    "pages": [
+                      "agent-os/security/authorization/overview",
+                      "agent-os/security/authorization/quickstart",
+                      "agent-os/security/authorization/tokens",
+                      "agent-os/security/authorization/self-hosted",
+                      "agent-os/security/authorization/scopes",
+                      "agent-os/security/authorization/roles",
+                      "agent-os/security/authorization/user-isolation",
+                      "agent-os/security/authorization/customization"
+                    ]
+                  }
+                ]
+              },
               {
                 "group": "Dynamic Agents",
                 "pages": [
@@ -4599,6 +4611,7 @@
                 "pages": [
                   "agent-os/usage/rbac/basic-symmetric",
                   "agent-os/usage/rbac/basic-asymmetric",
+                  "agent-os/usage/rbac/workos-byot",
                   "agent-os/usage/rbac/advanced-scopes",
                   "agent-os/usage/rbac/per-agent-permissions",
                   "agent-os/usage/rbac/custom-scope-mappings"
@@ -7938,6 +7951,10 @@
       "source": "/runtime/security-and-auth",
       "destination": "/features/security-and-auth"
     },
+    {
+      "source": "/agent-os/security/rbac",
+      "destination": "/agent-os/security/authorization/overview"
+    },
     {
       "source": "/runtime/interfaces",
       "destination": "/features/interfaces"
diff --git a/faq/rbac-auth-failed.mdx b/faq/rbac-auth-failed.mdx
index e08ae20fe..8c65b7537 100644
--- a/faq/rbac-auth-failed.mdx
+++ b/faq/rbac-auth-failed.mdx
@@ -60,7 +60,7 @@ The token is valid but AgentOS returns `403` on a specific endpoint.
 
 **Cause:** The token's `scopes` claim does not include the scope required by the endpoint. Unlike a `401`, the token itself is fine.
 
-**Fix:** Check the [Scope Reference](/agent-os/security/rbac#scope-reference) for which scope each endpoint needs. A few scopes act as gates in the platform and a token missing any of them fails before finer-grained checks run. See [Access Prerequisites](/agent-os/security/rbac#access-prerequisites) for the full list.
+**Fix:** Check the [Scope Reference](/agent-os/security/authorization/scopes#scope-reference) for which scope each endpoint needs. A few scopes act as gates in the platform and a token missing any of them fails before finer-grained checks run. See [Access Prerequisites](/agent-os/security/authorization/scopes#access-prerequisites) for the full list.
 
 ## Both security key and JWT authorization enabled
 
@@ -96,7 +96,7 @@ Pick one:
     unset OS_SECURITY_KEY
     ```
 
-    3. **Ensure Authorization is enabled** on the AgentOS Control Plane and set the verification key. [More info](/agent-os/security/rbac)
+    3. **Ensure Authorization is enabled** on the AgentOS Control Plane and set the verification key. [More info](/agent-os/security/authorization/overview)
 
     ```bash
     export JWT_VERIFICATION_KEY="your-public-key"
@@ -107,5 +107,5 @@ Pick one:
 ## Next Steps
 
 - [AgentOS Security overview](/agent-os/security/overview)
-- [RBAC reference](/agent-os/security/rbac)
+- [Authorization](/agent-os/security/authorization/overview)
 - [AuthorizationConfig reference](/reference/agent-os/authorization-config)
diff --git a/features/security-and-auth.mdx b/features/security-and-auth.mdx
index 3b50d6892..56b959b0d 100644
--- a/features/security-and-auth.mdx
+++ b/features/security-and-auth.mdx
@@ -1,6 +1,6 @@
 ---
 title: Security & Auth
-description: "Build a layered security model: authenticate every request, use RBAC for roles, and isolate data and access between users."
+description: "Build a layered security model: authenticate every request, use scopes and roles for permissions, and isolate data between users."
 ---
 
 AgentOS security works in layers. Each one stops a different class of attack, from unauthenticated requests at the edge to cross-user data access in the database.
@@ -8,11 +8,12 @@ AgentOS security works in layers. Each one stops a different class of attack, fr
 | Layer | What it stops | Mechanism |
 |-------|---------------|-----------|
 | **Authentication** | Unauthenticated requests | JWT validation at the middleware |
-| **Authorization** | Authenticated but out-of-scope requests | RBAC scopes on every endpoint |
+| **Authorization** | Authenticated but out-of-scope requests | Scope checks on every endpoint |
 | **Request isolation** | Concurrent requests reading each other's data | Fresh, isolated object per request |
 | **User isolation** | Cross-user data leakage on shared endpoints | Opt-in using `AuthorizationConfig(user_isolation=True)` |
 
-AgentOS give you good defaults at every layer
+AgentOS gives you good defaults at every layer.
+
 <Note>
 
 Network-layer controls (rate limiting, WAF, IP allowlists, mTLS) live at your reverse proxy or API gateway layer.
@@ -21,7 +22,7 @@ Network-layer controls (rate limiting, WAF, IP allowlists, mTLS) live at your re
 
 ## Authentication
 
-A production AgentOS sits behind JWT-validating middleware. Every request carries a token signed by the [control plane](https://os.agno.com); your service verifies it with a public key.
+A production AgentOS sits behind JWT-validating middleware. Every request carries a token signed by the [AgentOS control plane](https://os.agno.com); your service verifies it with a public key.
 
 ```python
 from agno.os import AgentOS
@@ -64,11 +65,11 @@ A small set of public routes are exempt from the JWT requirement: `/`, `/health`
   </Step>
 </Steps>
 
-The control plane keeps the private key. Your service only ever sees the public key. JWTs are signed by the control plane and verified by your service. See [Generate a Verification Key](/agent-os/security/rbac#generate-a-verification-key) for the full walkthrough.
+The AgentOS control plane keeps the private key. Your service only ever sees the public key. JWTs are signed by the control plane and verified by your service. See [Generate a Verification Key](/agent-os/security/authorization/quickstart#generate-a-verification-key) for the full walkthrough.
 
 ### Custom JWT configuration
 
-If you're issuing JWTs from your own auth provider, pass an `AuthorizationConfig`:
+If you're issuing JWTs from your own backend, or from a third-party identity provider like WorkOS, Auth0, or Okta, pass an `AuthorizationConfig`:
 
 ```python
 from agno.os import AgentOS
@@ -79,7 +80,7 @@ agent_os = AgentOS(
     db=db,
     authorization=True,
     authorization_config=AuthorizationConfig(
-        verification_keys=["public-key-1", "public-key-2"],   # rotation
+        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
@@ -88,15 +89,17 @@ agent_os = AgentOS(
 )
 ```
 
-`verification_keys` is a list, so you can rotate keys without downtime. Old tokens validate against the old key, and new tokens against the new. Drop the old key once tokens have expired.
+`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.
 
-## Authorization (RBAC scopes)
+For the full self-hosted setup including multi-issuer, see [Self-Hosted](/agent-os/security/authorization/self-hosted).
+
+## Authorization
 
-Every JWT carries a `scopes` claim. Endpoints are gated on scopes.
+Every JWT carries a claim listing the caller's permissions (`scopes` by default; configurable via `scopes_claim` if your provider uses a different name, like WorkOS's `permissions`). Endpoints are gated on those scopes.
 
 | Scope | Grants |
 |-------|--------|
@@ -105,7 +108,7 @@ Every JWT carries a `scopes` claim. Endpoints are gated on scopes.
 | `agents:*:run` | Run any agent (same pattern for teams, workflows) |
 | `agent_os:admin` | Full access including session, memory, and trace queries |
 
-The control plane mints each token with the appropriate scopes. Scopes are bundled into roles and assigned to users in the control plane: AgentOS ships three default roles (owner, admin, member), and custom roles are available on Enterprise. See the [RBAC scope reference](/agent-os/security/rbac#scope-reference) for the full scope list, [Default Roles](/agent-os/security/rbac#default-roles) for what each grants, and [Custom Roles](/agent-os/security/rbac#custom-roles-and-scopes) to compose your own.
+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](/agent-os/security/authorization/scopes#scope-reference) for the full scope list, [Default Roles](/agent-os/security/authorization/roles#default-roles) for what each grants, and [Custom Roles](/agent-os/security/authorization/roles#custom-roles) to compose your own.
 
 ## Request isolation
 
@@ -117,7 +120,7 @@ This is on by default for every run endpoint. There's nothing to configure.
 
 ## User isolation
 
-Per-user data isolation is **opt-in**. RBAC stays in force without it, but routes operate on the unscoped DB. A caller with `agents:my-agent:run` could read another user's sessions if they know the IDs. For multi-tenant deployments, turn it on:
+Per-user data isolation is **opt-in**. Authorization stays in force without it, but routes operate on the unscoped DB. A caller with `agents:my-agent:run` could read another user's sessions if they know the IDs. For multi-tenant deployments, turn it on:
 
 ```python
 from agno.os.config import AuthorizationConfig
diff --git a/reference/agent-os/authorization-config.mdx b/reference/agent-os/authorization-config.mdx
index fd51f7449..bcf182210 100644
--- a/reference/agent-os/authorization-config.mdx
+++ b/reference/agent-os/authorization-config.mdx
@@ -105,7 +105,7 @@ The JWKS file should follow the standard format:
 ## See Also
 
 - [Security Overview](/agent-os/security/overview) - AgentOS security overview
-- [RBAC Documentation](/agent-os/security/rbac) - Complete RBAC scopes and permissions
+- [Authorization](/agent-os/security/authorization/overview) - Scopes, roles, and access control
 - [JWT Middleware](/agent-os/middleware/jwt) - Advanced JWT configuration
 - [JWTMiddleware Reference](/reference/agent-os/jwt-middleware) - Middleware class reference
 
diff --git a/reference/agent-os/jwt-middleware.mdx b/reference/agent-os/jwt-middleware.mdx
index fc18e428e..2d6a128c9 100644
--- a/reference/agent-os/jwt-middleware.mdx
+++ b/reference/agent-os/jwt-middleware.mdx
@@ -192,6 +192,6 @@ After processing, the middleware stores the following in `request.state`:
 
 - [Security Overview](/agent-os/security/overview) - AgentOS security overview
 - [JWT Middleware Guide](/agent-os/middleware/jwt) - Configuration guide
-- [RBAC Documentation](/agent-os/security/rbac) - Complete scope reference
+- [Scopes](/agent-os/security/authorization/scopes) - Complete scope reference
 - [AuthorizationConfig](/reference/agent-os/authorization-config) - Authorization configuration
 
diff --git a/tutorials/dash/deploy-to-railway.mdx b/tutorials/dash/deploy-to-railway.mdx
index b6fb1668a..6388348c7 100644
--- a/tutorials/dash/deploy-to-railway.mdx
+++ b/tutorials/dash/deploy-to-railway.mdx
@@ -111,7 +111,7 @@ Dash holds a structural boundary between company data (`public`, read-only) and
 
 Local development sets `RUNTIME_ENV=dev` (via Docker Compose) and skips RBAC so you can iterate. Production defaults to `RUNTIME_ENV=prd` and enforces it.
 
-See [AgentOS Security](/agent-os/security/overview) and [RBAC](/agent-os/security/rbac).
+See [AgentOS Security](/agent-os/security/overview) and [Authorization](/agent-os/security/authorization/overview).
 
 ## Next
 
diff --git a/tutorials/scout/deploy-to-railway.mdx b/tutorials/scout/deploy-to-railway.mdx
index 154453838..ca67c73d4 100644
--- a/tutorials/scout/deploy-to-railway.mdx
+++ b/tutorials/scout/deploy-to-railway.mdx
@@ -52,7 +52,7 @@ MIIBIjANBgkq...
 -----END PUBLIC KEY-----
 ```
 
-The Agno control plane handles JWT issuance, session management, traces, metrics, and the web UI. Scout just verifies the JWTs it sees. See the [AgentOS security docs](/agent-os/security/overview) for the full picture.
+The AgentOS control plane handles JWT issuance, session management, traces, metrics, and the web UI. Scout just verifies the JWTs it sees. See the [AgentOS security docs](/agent-os/security/overview) for the full picture.
 
 <Warning>
   Opting out is not recommended. If you must run production without auth (e.g. inside a private VPC behind another auth layer), flip `authorization=False` in [`app/main.py`](https://github.com/agno-agi/scout/blob/main/app/main.py) before deploying. Without it, anyone who guesses your Railway domain can query your CRM, wiki, and connected sources.