Skip to content

rbac doc update #629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mishramonalisha76 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

rbac doc update #629

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5e9414f
docs-rbac-scopes
mishramonalisha76 Apr 21, 2026
d916f0c
rbac docs update
mishramonalisha76 Apr 30, 2026
a64fc0c
custom roles
mishramonalisha76 Apr 30, 2026
d5260f9
roles video
mishramonalisha76 May 4, 2026
0e4e6b8
cal link
mishramonalisha76 May 4, 2026
efb8c88
fixed merge conflcits
mishramonalisha76 May 4, 2026
f078c2d
removed todo
mishramonalisha76 May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 1 addition & 11 deletions agent-os/security/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,19 +38,9 @@ Set the `JWT_VERIFICATION_KEY` environment variable to your public key in your `
export JWT_VERIFICATION_KEY="your-public-key"
```

You can generate a key pair from the control plane when connecting a new OS or from the Settings page for an existing OS.

<video
autoPlay
muted
controls
className="w-full aspect-video"
src="/videos/auth-on-connect-web.mp4"
Copy link
Copy Markdown
Contributor

@kausmeows kausmeows May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we're not showing this video lets remove it from the directory too? if its not being used anywhere.

Copy link
Copy Markdown
Contributor Author

@mishramonalisha76 mishramonalisha76 May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are showing this video

></video>

Requests without a valid JWT return `401 Unauthorized`. Requests with insufficient scopes return `403 Forbidden`.

See [RBAC Documentation](/agent-os/security/rbac) for scope format, available scopes, and endpoint mappings.
See the [RBAC documentation](/agent-os/security/rbac) for the full setup flow, scope reference, and endpoint mappings.

<CardGroup cols={2}>
<Card
Expand Down
156 changes: 147 additions & 9 deletions agent-os/security/rbac.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,45 @@
app = agent_os.get_app()
```

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"
```


## Generate a Verification Key

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

<Steps>
<Step title="Toggle JWT authorization">
Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.

{/* TODO: screenshot of the toggle */}
Copy link
Copy Markdown
Contributor

@kausmeows kausmeows May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes pls, this would be helpful

Copy link
Copy Markdown
Contributor Author

@mishramonalisha76 mishramonalisha76 May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no we don't need this, we have a video showing the flow below . This was leftover code

</Step>

<Step title="Copy the public key">
A modal appears with the public key for your AgentOS.
</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.

<video
autoPlay
muted
controls
className="w-full aspect-video"
src="/videos/auth-on-connect-web.mp4"
></video>

## Scope Format

Expand All @@ -60,19 +95,53 @@
| `resource:*:action` | `agents:*:read` | Wildcard (equivalent to global) |
| `agent_os:admin` | - | Full access to all endpoints |


## Complete Scope Reference

### Organization Scopes

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

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

### Admin Scopes

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



### AgentOS config Scopes

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

### System Scopes

### Registry Scopes

| Scope | Description |
|-------|-------------|
| `system:read` | View system configuration and available models |
| `registry:read` | View the code-defined registry (tools, models, databases) |

### Component Scopes

| Scope | Description |
|-------|-------------|
| `components:read` | List and view components and their configs |

Check warning on line 142 in agent-os/security/rbac.mdx

View check run for this annotation

Mintlify / Mintlify Validation (agno-v2) - vale-spellcheck

agent-os/security/rbac.mdx#L142 

Did you really mean 'configs'?
| `components:write` | Create and update components and configs |

Check warning on line 143 in agent-os/security/rbac.mdx

View check run for this annotation

Mintlify / Mintlify Validation (agno-v2) - vale-spellcheck

agent-os/security/rbac.mdx#L143 

Did you really mean 'configs'?
| `components:delete` | Delete components and configs |

Check warning on line 144 in agent-os/security/rbac.mdx

View check run for this annotation

Mintlify / Mintlify Validation (agno-v2) - vale-spellcheck

agent-os/security/rbac.mdx#L144 

Did you really mean 'configs'?

### Agent Scopes

Expand Down Expand Up @@ -176,8 +245,16 @@
<Tab title="System">
| Endpoint | Required Scope |
|----------|----------------|
| `GET /config` | `system:read` |
| `GET /models` | `system:read` |
| `GET /config` | `config:read` |
| `GET /models` | `config:read` |
| `POST /databases/all/migrate` | `config:write` |
| `POST /databases/*/migrate` | `config:write` |
</Tab>

<Tab title="Registry">
| Endpoint | Required Scope |
|----------|----------------|
| `GET /registry` | `registry:read` |
</Tab>

<Tab title="Agents">
Expand Down Expand Up @@ -236,7 +313,7 @@
|----------|----------------|
| `GET /memories` | `memories:read` |
| `GET /memories/*` | `memories:read` |
| `GET /memory_topics` | `memories:read` |

Check warning on line 316 in agent-os/security/rbac.mdx

View check run for this annotation

Mintlify / Mintlify Validation (agno-v2) - vale-spellcheck

agent-os/security/rbac.mdx#L316 

Did you really mean 'memory_topics'?
| `GET /user_memory_stats` | `memories:read` |
| `POST /memories` | `memories:write` |
| `PATCH /memories/*` | `memories:write` |
Expand All @@ -251,8 +328,11 @@
| `GET /knowledge/content` | `knowledge:read` |
| `GET /knowledge/content/*` | `knowledge:read` |
| `GET /knowledge/config` | `knowledge:read` |
| `GET /knowledge/*/sources` | `knowledge:read` |
| `GET /knowledge/*/sources/*/files` | `knowledge:read` |
| `POST /knowledge/search` | `knowledge:read` |
| `POST /knowledge/content` | `knowledge:write` |
| `POST /knowledge/remote-content` | `knowledge:write` |
| `PATCH /knowledge/content/*` | `knowledge:write` |
| `DELETE /knowledge/content` | `knowledge:delete` |
| `DELETE /knowledge/content/*` | `knowledge:delete` |
Expand Down Expand Up @@ -281,6 +361,7 @@
| `GET /traces` | `traces:read` |
| `GET /traces/*` | `traces:read` |
| `GET /trace_session_stats` | `traces:read` |
| `POST /traces/search` | `traces:read` |
</Tab>

<Tab title="Schedules">
Expand Down Expand Up @@ -308,8 +389,35 @@
| `POST /approvals/*/resolve` | `approvals:write` |
| `DELETE /approvals/*` | `approvals:delete` |
</Tab>

<Tab title="Components">
| Endpoint | Required Scope |
|----------|----------------|
| `GET /components` | `components:read` |
| `GET /components/*` | `components:read` |
| `GET /components/*/configs` | `components:read` |
| `GET /components/*/configs/*` | `components:read` |
| `GET /components/*/configs/current` | `components:read` |
| `POST /components` | `components:write` |
| `POST /components/*/configs` | `components:write` |
| `POST /components/*/configs/*/set-current` | `components:write` |
| `PATCH /components/*` | `components:write` |
| `PATCH /components/*/configs/*` | `components:write` |
| `DELETE /components/*` | `components:delete` |
| `DELETE /components/*/configs/*` | `components:delete` |
</Tab>
</Tabs>

## Access Prerequisites

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

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

## Custom Scope Mappings

Customize or extend the default scope mappings using the JWT middleware:
Expand Down Expand Up @@ -339,6 +447,36 @@

Custom scope mappings are additive to the defaults. To override a default, specify the same route pattern with your custom scopes.

## Custom Roles and Scopes

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

## JWT Token Structure

Your JWT tokens should include:
Expand Down
Binary file added videos/roles.mp4
View file
Open in desktop
Binary file not shown.
Loading