auth doc rvamp

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>

agent-os/control-plane.mdx

@@ -77,7 +77,7 @@
 
 Build agents, teams, and workflows visually on a live canvas. Drag, drop, configure, and deploy without leaving the control plane.
 
 {/* TODO: replace placeholder with the real Studio walkthrough video */}
 <Frame>
   <video
     autoPlay
@@ -204,7 +204,7 @@
 
 ## Schedules
 
 Automate agents, teams, and workflows via AgentOS cron schedules. Configure custom intervals, retry logic, and timezones. Use the Control Panel to monitor run history, enable/disable job states, or trigger manual executions.
 
 For setup and API details, see [Scheduler](/agent-os/scheduler/overview) documentation.
 
@@ -254,7 +254,7 @@
   </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 @@
 | **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

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"

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>
 

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                                           |

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

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>