agno-agi · mishramonalisha76 · Apr 21, 2026 · Apr 30, 2026 · Apr 30, 2026 · May 4, 2026
diff --git a/agent-os/custom-fastapi/overview.mdx b/agent-os/custom-fastapi/overview.mdx
@@ -171,6 +171,30 @@ if __name__ == "__main__":
     agent_os.serve(app="custom_fastapi_app:app", reload=True)
 ```
 
+Run it end to end:
+
+<Steps>
+  <Snippet file="create-venv-step.mdx" />
+
+  <Step title="Set environment variables">
+    ```bash
+    export ANTHROPIC_API_KEY=your_anthropic_api_key
+    ```
+  </Step>
+
+  <Step title="Install dependencies">
+    ```bash
+    uv pip install -U agno anthropic fastapi uvicorn sqlalchemy
+    ```
+  </Step>
+
+  <Step title="Run the example">
+    ```bash
+    python custom_fastapi_app.py
+    ```
+  </Step>
+</Steps>
+
 
 ## Middleware and Dependencies
 
@@ -234,5 +258,4 @@ for route in routes:
 ## Developer Resources
 
 - [AgentOS Reference](/reference/agent-os/agent-os)
-- [Full Example](/agent-os/usage/custom-fastapi)
 - [FastAPI Documentation](https://fastapi.tiangolo.com/)
diff --git a/agent-os/middleware/jwt.mdx b/agent-os/middleware/jwt.mdx
@@ -225,23 +225,48 @@ app.add_middleware(
 For detailed RBAC documentation including all available scopes and default mappings, see [RBAC Documentation](/agent-os/security/rbac).
 </Tip>
 
+## User Isolation
+
+RBAC controls which endpoints a caller can hit. User isolation controls which rows they can see and mutate. The two are independent toggles.
+
+```python jwt_with_user_isolation.py
+app.add_middleware(
+    JWTMiddleware,
+    verification_keys=["your-jwt-key"],
+    authorization=True,
+    user_isolation=True,
+)
+```
+
+When `user_isolation=True`, non-admin callers are scoped to their own `user_id` (from the JWT `sub` claim) for sessions, memory, and traces. Callers holding `admin_scope` bypass isolation. See [Per-User Data Isolation](/agent-os/security/rbac#per-user-data-isolation) for the full behavior.
 
 ## Excluded Routes
 
-Skip middleware for specific routes:
+These routes skip JWT and RBAC checks by default:
+
+```python
+["/", "/health", "/info", "/docs", "/redoc", "/openapi.json", "/docs/oauth2-redirect"]
+```
+
+Override them with `excluded_route_paths`:
 
 ```python jwt_excluded_routes.py
 app.add_middleware(
     JWTMiddleware,
     verification_keys=["your-key"],
     excluded_route_paths=[
         "/health",
-        "/auth/login", 
+        "/auth/login",
         "/auth/register",
         "/public/*",  # Wildcards supported
     ]
 )
 ```
+
+<Warning>
+`excluded_route_paths` replaces the defaults, it is not additive. Re-include any default routes you want to keep.
+</Warning>
+
 ## Configuration Options
 
 See the [JWTMiddleware Reference](/reference/agent-os/jwt-middleware) for the complete list of configuration options.
@@ -282,6 +307,7 @@ See the [JWTMiddleware Reference](/reference/agent-os/jwt-middleware) for the co
 | `authorization` | Enable RBAC scope checking | `False` |
 | `verify_audience` | Verify `aud` claim matches AgentOS ID | `False` |
 | `audience` | Expected audience claim to validate against the token's audience claim | `AgentOS ID` |
+| `user_isolation` | Opt in to per-user data isolation. When `True`, AgentOS uses the JWT `sub` claim as the `user_id` for every non-admin caller: reads are scoped to it and writes are coerced to it, so callers can't see or persist other users' rows. Callers holding `admin_scope` bypass it. | `False` |
 | `scope_mappings` | Custom route-to-scope mappings (additive to defaults) | `None` |
 | `admin_scope` | Scope that grants full admin access | `"agent_os:admin"` |
 | `excluded_route_paths` | Routes to skip JWT/RBAC checks | See below |

diff --git a/agent-os/middleware/overview.mdx b/agent-os/middleware/overview.mdx
@@ -9,12 +9,12 @@ keywords: [middleware, fastapi middleware, agentos middleware, jwt middleware, c
     <Tooltip tip="Introduced in v2.1.0" cta="View release notes" href="https://github.com/agno-agi/agno/releases/tag/v2.1.0">v2.1.0</Tooltip>
 </Badge>
 
-AgentOS is built on FastAPI, allowing you to add any [FastAPI/Starlette compatible middleware](https://fastapi.tiangolo.com/tutorial/middleware/) for authentication, logging, monitoring, and security. Agno provides built-in JWT middleware for authentication, and you can create custom middleware for rate limiting, request logging, and security headers.
+AgentOS is built on FastAPI, so you can add any [FastAPI/Starlette-compatible middleware](https://fastapi.tiangolo.com/tutorial/middleware/) for authentication, logging, monitoring, and security.
 
-Additionally, Agno provides some built-in middleware for common use cases, including authentication.
+Agno ships a built-in JWT middleware for authentication. You can write your own custom middleware for rate limiting, request logging, and security headers.
 
 See the following guides:
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card
     title="Custom Middleware"
     icon="code"
@@ -29,13 +29,6 @@ See the following guides:
   >
     Built-in JWT authentication with automatic parameter injection and claims extraction.
   </Card>
-  <Card
-    title="RBAC"
-    icon="lock"
-    href="/agent-os/security/rbac"
-  >
-    Use the built-in JWT middleware with Role-based access control and fine-grained permission scopes.
-  </Card>
 </CardGroup>
 
 

diff --git a/agent-os/security/rbac.mdx b/agent-os/security/rbac.mdx
@@ -42,7 +42,6 @@ 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.

diff --git a/agent-os/usage/custom-fastapi.mdx b/agent-os/usage/custom-fastapi.mdx
diff --git a/videos/roles.mp4 → images/roles.mp4 b/videos/roles.mp4 → images/roles.mp4
diff --git a/reference/agent-os/authorization-config.mdx b/reference/agent-os/authorization-config.mdx
@@ -19,6 +19,7 @@ from agno.os.config import AuthorizationConfig
 | `jwks_file` | `Optional[str]` | `None` | Path to a static JWKS (JSON Web Key Set) file containing public keys. Keys are matched by `kid` (key ID) from the JWT header. Alternative to `verification_keys` for RSA key management. |
 | `algorithm` | `Optional[str]` | `RS256` | JWT algorithm for token verification. Common options: `RS256` (asymmetric), `HS256` (symmetric). |
 | `verify_audience` | `Optional[bool]` | `False` | Whether to verify the audience claim of the JWT token. This should not be enabled for AgentOS Control Plane traffic. |
+| `user_isolation` | `bool` | `False` | Opt in to per-user data isolation. When `True`, AgentOS uses the JWT `sub` claim as the `user_id` for every non-admin caller: reads are scoped to it and writes are coerced to it, so callers can't see or persist other users' rows. Callers holding `admin_scope` bypass it. Requires a database that records `user_id`. |
 
 ## Usage
 

diff --git a/reference/agent-os/jwt-middleware.mdx b/reference/agent-os/jwt-middleware.mdx
@@ -21,21 +21,22 @@ from agno.os.middleware.jwt import TokenSource
 | `secret_key` | `Optional[str]` | `None` | **(Deprecated)** Use `verification_keys` instead. |
 | `algorithm` | `str` | `"RS256"` | JWT algorithm (RS256, HS256, ES256, etc.) |
 | `validate` | `bool` | `True` | Whether to validate JWT tokens |
-| `authorization` | `Optional[bool]` | `None` | Enable RBAC scope checking |
+| `authorization` | `Optional[bool]` | `None` | Enable RBAC scope checking. If left `None` and `scope_mappings` is provided, RBAC is auto-enabled. |
 | `token_source` | `TokenSource` | `TokenSource.HEADER` | Where to extract JWT token from |
 | `token_header_key` | `str` | `"Authorization"` | Header key for Authorization |
 | `cookie_name` | `str` | `"access_token"` | Cookie name for JWT token |
 | `scopes_claim` | `str` | `"scopes"` | JWT claim name for scopes |
 | `user_id_claim` | `str` | `"sub"` | JWT claim name for user ID |
 | `session_id_claim` | `str` | `"session_id"` | JWT claim name for session ID |
 | `audience_claim` | `str` | `"aud"` | JWT claim name for audience/OS ID |
-| `audience` | `Optional[Union[str, Iterable[str]]]` | `None` | Expected audience claim to validate against the token's audience claim. Defaults to the AgentOS ID. |
+| `audience` | `Optional[Union[str, Iterable[str]]]` | `None` | Expected audience(s) to validate the token's `aud` claim against. Accepts a string or a list of strings; the token matches if its audience matches any of them. Defaults to the AgentOS ID. |
 | `verify_audience` | `bool` | `False` | Verify `aud` claim matches AgentOS ID |
 | `dependencies_claims` | `Optional[List[str]]` | `None` | Claims to extract for `dependencies` parameter |
 | `session_state_claims` | `Optional[List[str]]` | `None` | Claims to extract for `session_state` parameter |
 | `scope_mappings` | `Optional[Dict[str, List[str]]]` | `None` | Custom route-to-scope mappings (additive to defaults) |
-| `excluded_route_paths` | `Optional[List[str]]` | See below | Routes to skip JWT/RBAC checks |
+| `excluded_route_paths` | `Optional[List[str]]` | See below | Routes to skip JWT/RBAC checks. |
 | `admin_scope` | `Optional[str]` | `"agent_os:admin"` | Scope that grants full admin access |
+| `user_isolation` | `bool` | `False` | Opt in to per-user data isolation. When `True`, AgentOS uses the JWT `sub` claim as the `user_id` for every non-admin caller: reads are scoped to it and writes are coerced to it, so callers can't see or persist other users' rows. Callers holding `admin_scope` bypass it. Requires a database that records `user_id`. |
 
 ## TokenSource Enum
 
@@ -51,6 +52,7 @@ from agno.os.middleware.jwt import TokenSource
 [
     "/",
     "/health",
+    "/info",
     "/docs",
     "/redoc",
     "/openapi.json",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -42,7 +42,6 @@ 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.
Expand Down