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

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.

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.

How organization and workspace changes combine

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

The platform defaults (the matrix below).
The organization's changes, for workspaces in that organization.
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

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.

How access is evaluated

For every request:

The credential is resolved to a user; an API key acts as its owner.
A workspace key used with another workspace's slug is refused: 403.
A platform admin acts as Admin in any workspace.
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.
The role's permissions are worked out as described above.
The route's permission must be among them; otherwise 403.

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

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

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.

Workspace

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

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

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

Connections

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

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

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

Flows

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

Observability

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

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

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

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

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

Workspace permissions

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

Usage

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

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

On this page