> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Roles and permissions

Roles and permissions [#roles-and-permissions]

Each workspace member has one role, and the role's permissions decide which API routes they and their API keys can call.

Built-in roles [#built-in-roles]

| Role   | `role_slug` | Can, by default                                                                                                            |
| ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| Member | `member`    | Work with agents, connections, MCP connections, integrations and flows; read apps, observability, API keys and magic links |
| Editor | `editor`    | Everything a Member can, plus edit apps, create and edit API keys and magic links                                          |
| Admin  | `admin`     | Everything, including members, invites, roles and deletes                                                                  |

The exact defaults are in the [permission matrix](#permission-matrix).

Custom roles [#custom-roles]

* Custom roles are defined on an organization and appear in every workspace of that organization, now and later.
* A new custom role starts with no permissions.
* Workspaces outside an organization have only the built-in roles.
* A custom role still held by a member or a pending invite cannot be deleted: `409`. Built-in roles cannot be deleted.
* Create them with `POST /api/v1/platform-admin/organizations/{org_id}/roles/`; see [Organizations API](../platform/organizations).

How organization and workspace changes combine [#how-organization-and-workspace-changes-combine]

A role's permissions are worked out in this order, each step overriding the previous one:

1. The platform defaults (the matrix below).
2. The organization's changes, for workspaces in that organization.
3. The workspace's own changes. A workspace can add a permission its organization removed, or remove one it added.

`inherited_permission_ids` on a role is what it would have without the workspace's own changes; `POST /api/v1/spaces/current/roles/reset-defaults/` drops those changes.

Workspace endpoints [#workspace-endpoints]

Every route selects its workspace with `X-Space-Slug`.

| Method | URL                                                                   | Input                          | Returns                                                                       | Auth          |
| ------ | --------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- | ------------- |
| `GET`  | `/api/v1/spaces/current/roles/`                                       |                                | Roles with `id`, `slug`, `name`, `permission_ids`, `inherited_permission_ids` | Key or bearer |
| `GET`  | `/api/v1/spaces/current/permissions/`                                 |                                | Permissions with `id`, `name`, `resource_type`, `action`                      | Key or bearer |
| `PUT`  | `/api/v1/spaces/current/roles/{role_id}/permissions/{permission_id}/` | `{"enabled": true}` or `false` | The updated role                                                              | Key or bearer |
| `POST` | `/api/v1/spaces/current/roles/reset-defaults/`                        |                                | All roles, with the workspace's own changes removed                           | Key or bearer |

* `PUT` changes the role in this workspace only. An unknown `role_id` or `permission_id` returns `404` `Space role not found` or `Permission not found`.
* Organization-wide changes use the same shape under `/api/v1/platform-admin/organizations/{org_id}/roles/`; see [Organizations API](../platform/organizations).

How access is evaluated [#how-access-is-evaluated]

For every request:

1. The credential is resolved to a user; an API key acts as its owner.
2. A workspace key used with another workspace's slug is refused: `403`.
3. A platform admin acts as Admin in any workspace.
4. Otherwise the user's role in the selected workspace applies; a user with no role there gets `403` `User does not have access to the selected space`.
5. The role's permissions are worked out as described above.
6. The route's permission must be among them; otherwise `403`.

Worked example [#worked-example]

Organization Acme has workspaces Ops and Sales. Ana is a Member in both; Ben holds the custom role Analyst in Ops.

| Change                                           | Ana in Ops                               | Ana in Sales                 | Ben in Ops            |
| ------------------------------------------------ | ---------------------------------------- | ---------------------------- | --------------------- |
| Defaults; Analyst is given only Read connections | 28 permissions, incl. Delete connections | 28, incl. Delete connections | Read connections only |
| Acme removes Delete connections from Member      | 27                                       | 27                           | unchanged             |
| Ops adds Delete connections back to Member       | 28                                       | 27                           | unchanged             |

Who can change roles [#who-can-change-roles]

| Rule                                                                     | Error                                                         |
| ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| Changing a role needs the Workspace roles permissions (Admin by default) | `403`                                                         |
| You can turn on only permissions you hold yourself                       | `403` "You can only grant permissions you hold"               |
| You can assign only a role whose permissions you all hold                | `403` "You can only assign a role whose permissions you hold" |

Platform admins are not limited by the last two rules.

Permission matrix [#permission-matrix]

Every permission below can also be given to a custom role. Legacy agent permissions are hidden in the web app; the legacy agent routes accept them or the matching Agents permission.

{/* permission-matrix:start (generated by scripts/generate-permission-matrix.mjs) */}

Workspace [#workspace]

| Permission                                              | Member | Editor | Admin |
| ------------------------------------------------------- | ------ | ------ | ----- |
| Manage workspace settings (`workspace:manage_settings`) | —      | —      | ✓     |

Agents [#agents]

| Permission                                  | Member | Editor | Admin |
| ------------------------------------------- | ------ | ------ | ----- |
| Read Agents (`configurable_agent:read`)     | ✓      | ✓      | ✓     |
| Create Agents (`configurable_agent:create`) | ✓      | ✓      | ✓     |
| Edit Agents (`configurable_agent:edit`)     | ✓      | ✓      | ✓     |
| Delete Agents (`configurable_agent:delete`) | ✓      | ✓      | ✓     |

Apps [#apps]

| Permission                                | Member | Editor | Admin |
| ----------------------------------------- | ------ | ------ | ----- |
| Read apps (`app:read`)                    | ✓      | ✓      | ✓     |
| Edit apps (`app:edit`)                    | —      | ✓      | ✓     |
| Manage app secrets (`app:manage_secrets`) | —      | —      | ✓     |

Connections [#connections]

| Permission                               | Member | Editor | Admin |
| ---------------------------------------- | ------ | ------ | ----- |
| Read connections (`connection:read`)     | ✓      | ✓      | ✓     |
| Create connections (`connection:create`) | ✓      | ✓      | ✓     |
| Edit connections (`connection:edit`)     | ✓      | ✓      | ✓     |
| Delete connections (`connection:delete`) | ✓      | ✓      | ✓     |

MCP connections [#mcp-connections]

| Permission                                       | Member | Editor | Admin |
| ------------------------------------------------ | ------ | ------ | ----- |
| Read MCP Connections (`mcp_connection:read`)     | ✓      | ✓      | ✓     |
| Create MCP Connections (`mcp_connection:create`) | ✓      | ✓      | ✓     |
| Edit MCP Connections (`mcp_connection:edit`)     | ✓      | ✓      | ✓     |
| Delete MCP Connections (`mcp_connection:delete`) | ✓      | ✓      | ✓     |

Integrations [#integrations]

| Permission                                 | Member | Editor | Admin |
| ------------------------------------------ | ------ | ------ | ----- |
| Read Integrations (`integration:read`)     | ✓      | ✓      | ✓     |
| Create Integrations (`integration:create`) | ✓      | ✓      | ✓     |
| Edit Integrations (`integration:edit`)     | ✓      | ✓      | ✓     |
| Delete Integrations (`integration:delete`) | ✓      | ✓      | ✓     |

Flows [#flows]

| Permission                           | Member | Editor | Admin |
| ------------------------------------ | ------ | ------ | ----- |
| Read workflows (`workflow:read`)     | ✓      | ✓      | ✓     |
| Create workflows (`workflow:create`) | ✓      | ✓      | ✓     |
| Edit workflows (`workflow:edit`)     | ✓      | ✓      | ✓     |
| Delete workflows (`workflow:delete`) | ✓      | ✓      | ✓     |

Observability [#observability]

| Permission                                | Member | Editor | Admin |
| ----------------------------------------- | ------ | ------ | ----- |
| Read observability (`observability:read`) | ✓      | ✓      | ✓     |

API keys [#api-keys]

| Permission                         | Member | Editor | Admin |
| ---------------------------------- | ------ | ------ | ----- |
| Read API keys (`api_key:read`)     | ✓      | ✓      | ✓     |
| Create API keys (`api_key:create`) | —      | ✓      | ✓     |
| Edit API keys (`api_key:edit`)     | —      | ✓      | ✓     |
| Delete API keys (`api_key:delete`) | —      | —      | ✓     |

Magic links [#magic-links]

| Permission                              | Member | Editor | Admin |
| --------------------------------------- | ------ | ------ | ----- |
| Read magic links (`chat_link:read`)     | ✓      | ✓      | ✓     |
| Create magic links (`chat_link:create`) | —      | ✓      | ✓     |
| Edit magic links (`chat_link:edit`)     | —      | ✓      | ✓     |
| Delete magic links (`chat_link:delete`) | —      | —      | ✓     |

Workspace members [#workspace-members]

| Permission                                   | Member | Editor | Admin |
| -------------------------------------------- | ------ | ------ | ----- |
| List space members (`space_member:list`)     | —      | —      | ✓     |
| Create space members (`space_member:create`) | —      | —      | ✓     |
| Edit space members (`space_member:edit`)     | —      | —      | ✓     |
| Delete space members (`space_member:delete`) | —      | —      | ✓     |

Workspace roles [#workspace-roles]

| Permission                           | Member | Editor | Admin |
| ------------------------------------ | ------ | ------ | ----- |
| List space roles (`space_role:list`) | —      | —      | ✓     |
| Edit space roles (`space_role:edit`) | —      | —      | ✓     |

Workspace permissions [#workspace-permissions]

| Permission                                       | Member | Editor | Admin |
| ------------------------------------------------ | ------ | ------ | ----- |
| List space permissions (`space_permission:list`) | —      | —      | ✓     |

Usage [#usage]

| Permission                        | Member | Editor | Admin |
| --------------------------------- | ------ | ------ | ----- |
| Read Usage Reports (`usage:read`) | —      | —      | ✓     |

Legacy agents (hidden in the UI) [#legacy-agents-hidden-in-the-ui]

| Permission                        | Member | Editor | Admin |
| --------------------------------- | ------ | ------ | ----- |
| Read Agent Content (`agent:read`) | ✓      | ✓      | ✓     |
| Create Agent (`agent:create`)     | ✓      | ✓      | ✓     |
| Edit Agent (`agent:edit`)         | ✓      | ✓      | ✓     |
| Delete Agent (`agent:delete`)     | ✓      | ✓      | ✓     |

{/* permission-matrix:end */}