Custom roles

A custom role is a named set of permissions from a fixed catalog. It replaces a member's system role. A custom-role member is ranked as viewer for any role-only check, but inherits nothing from viewer: they can reach only what the role's permissions grant.

The permission catalog

Permissions are named resource:aspect. Most resources have view and manage (or write). Agents, Tool Registry, MCP Servers, Alerts, Members & Roles and API keys also have a separate delete, so a role can edit an agent without being able to purge one.

Connectors, Workspaces and Org Settings aren't in the catalog. Only admins and owners can use them.

Agents

Guardrails

Tool & MCP governance

Audit & observability

Session Insights

sessions:view discloses one person's numbers to another, so Viewer and Builder never get it by default; only an explicit grant does. The checkbox appears only on plans that include Session Insights.

Billing & budgets

Alerts

Members & roles

Identity & access infra

Model & provider config

Create and assign a role

1. Open Members → Roles

   Needs admin, owner, or a custom role with members:view. The tab lists every role with its Type (System, System (edited) or Custom), Permissions count and Members count.

2. New role: name it and pick permissions

   Tick permissions from the permission catalog. To start from an existing role, choose Clone from its row menu.

3. Create role

   A permission outside the catalog is rejected. The role starts with no members.

4. Assign it

   On the Members tab, open a member's ⋮ menu and choose Change role. Custom roles appear alongside the system roles. You can also pick one when sending an invite.

To delete a role that still has members, pick a role to reassign them to in the same step.

Editing Builder and Viewer

Each workspace decides which catalog permissions Builder and Viewer carry. Owner and Admin can't be edited.

1. Open Members → Roles

   Open the row menu on Builder or Viewer and choose Edit.

2. Tick the permissions the role should carry

   Any catalog permission can be added, and the list can be empty. You can only grant permissions you hold, so only an owner can add identity_config:write. A built-in role's name and tags can't be changed.

3. Save changes

   The change applies to everyone with that role, including people who join later. The row's type changes to System (edited).

To undo, choose Reset to default from the same menu. It appears only on an edited role.

Neither default includes observability:view or traces:read:workspace. Builders retain personal trace access for their own calls and currently owned agents through traces:read. Only an explicit workspace-content grant or an administrator role allows other members’ call content. The Roles editor asks for acknowledgement when adding workspace call-content access, including when cloning a role.

How this differs from a custom role:

• A builder or viewer with a permission such as agents:write still acts only on what they own. Changing another member's agent or key needs Admin, or a custom role with that permission.
• Access outside the catalog, such as calling models through the gateway, stays with the role whatever you tick.

If a workspace's auto-join role is Builder, anything you add to Builder also reaches people who auto-join.

Permissions that depend on others

Guardrails, Tool Registry and MCP Servers load the agent list, so they're locked to whatever the Agents permission allows. API Keys needs models:view for its model picker, so Keys access is locked to that too. billing:read isn't needed for API Keys; without it, only the per-key spend column is empty.

Read scopes

A member can also hold the read scopes audit:read and traces:read on top of their role. They're set automatically when a member is invited or changes role, unless the member already has customized scopes:

• Viewer: audit:read.
• Builder: audit:read and traces:read (their own traces only).
• Admin and owner need none; they already read everything.

How a request is checked

Each endpoint requires a minimum role, a specific permission, or either. A custom-role member never passes a role-only check, because their rank is viewer. A builder or viewer is decided by permission alone wherever a member-level permission applies (agents, tools, MCP, guardrails view, audit, models, routing).

A blocked request returns 403 naming the role or permission that would have let it through. See Errors and refusals.

Next

Existing saved observability:view grants are not converted into workspace call-content grants automatically. Review intended broad access and explicitly grant traces:read:workspace; save dates do not establish an administrator’s intent. Unbound service keys also need the explicit workspace scope for project-wide reads.