Skip to main content
Custom roles let account admins define their own permission sets and limit access to specific package groups or connection groups. Use a custom role when the predefined roles (Owner, Admin, Operator, Editor, Reader) grant either too much or too little access for a team. Custom roles are an opt-in feature. If you do not see the Roles tab under Settings > User Management, contact Support to enable them on your account.
User Management Roles tab listing predefined and custom roles

​
How custom roles work

A custom role has three parts:
  • Permissions: the list of actions members assigned to the role can perform (for example, view packages, create connections, run jobs).
  • Package group scope: which package groups the role applies to.
  • Connection group scope: which connection groups the role applies to.
Package groups were previously called workspaces. The role-creation form, the API field names (workspace_scope, workspace_ids), and the workspace-domain permission keys (viewWorkspace, createWorkspace, and so on) still use the legacy term. They refer to the same thing.
Each scope accepts one of three values: Scopes are strict: choosing Specific means the role grants access to only those resources. Resources without a package group or connection group (orphans) are not included. Package-group-scoped permissions cover package groups, packages, jobs, schedules, and package templates. Connection-group-scoped permissions cover connections and connection groups. Account-level permissions (clusters, hooks, members, billing, global variables) are not affected by resource scope and are configured under Global Permissions instead. The package group scope and connection group scope also control visibility of the resources that belong to those groups:
  • Packages: a package is visible only when it belongs to a package group the role allows. Packages outside the role’s scope are hidden from the packages list, designer, and search.
  • Jobs: a job is visible only when its package belongs to a package group the role allows. Jobs whose package is outside the role’s scope are hidden, even from the jobs list.
  • Schedules: a schedule is visible only when every package it triggers is in scope. If a schedule references at least one package the user cannot see, the entire schedule is hidden so the scope does not leak the existence of out-of-scope packages.
  • Connections: a connection is visible only when it belongs to a connection group the role allows. Connections without a connection group are not visible to a scoped role.
When the scope is No package groups, members assigned to the role cannot see any package, job, schedule, or package group, even ones with no package group assigned. The same rule applies to connections under No connection groups.

​
How custom roles combine with predefined roles

A member can be assigned a predefined role, one or more custom roles, or both. The two interact as follows: Use a custom role on its own when you want to restrict a member to a specific set of package groups or connection groups. Combine a predefined role with a custom role when you want the predefined role’s defaults plus some extra permissions (for example, an Editor who also needs to create clusters).

​
Access Level presets

When you create a role, the Access Level section offers four presets that pre-fill the permission checkboxes: Reader, Editor, and Operator presets lock the checkboxes to make the intent explicit. Switch to Custom to edit individual permissions.
Role creation form with the Operator preset selected and Specific scope chosen for one package group and one connection group

​
Creating a custom role

Prerequisites:
  • You must be an Owner or Admin on the account.
  • Custom roles must be enabled for your account.
1
On the left menu, open Settings, then User Management, and switch to the Roles tab.
2
Click Create New Role.
3
Enter a Name and an optional Description. Both appear in the Roles list and in the Assigned Roles picker when inviting members.
4
In Resource Scope, choose a package group scope and a connection group scope. Pick All, Specific (then add the package groups or connection groups), or No. The role-creation form labels the package group axis as “Workspaces” (legacy term), but the meaning is the same.
5
In Access Level, pick Reader, Editor, Operator, or Custom. With Custom, tick individual permissions in the resource grid below.
6
Optionally expand Global Permissions and grant account-wide capabilities (managing members, viewing the account profile, viewing billing).
Role creation form with the Custom preset, all-scope, and the Global Permissions section visible
7
Click Create Role.

​
Assigning a custom role to a member

1
Go to Settings > User Management, then switch to the Users tab.
2
Open the member you want to update, or click Invite New Member to add a new one.
3
Under Assigned Roles, tick one or more roles. Each role is labeled PREDEFINED or CUSTOM so you can tell them apart at a glance. You can combine a predefined role with one or more custom roles, or assign multiple custom roles together.
Invite New Member dialog showing the Assigned Roles picker with custom and predefined role badges
4
Click Invite member (or Save when editing an existing member).
A member’s effective permissions are the union of every role they have assigned. If they hold a predefined role, that role’s account-wide grants stay in effect alongside any custom role.

​
Assigning users from the role

You can also manage a role’s assignees from the role itself instead of editing every member individually. Use this path when you need to add or remove several users on the same role in one step.
1
Go to Settings > User Management, then switch to the Roles tab.
2
Open the Assign Users dialog for the role using any of these entry points:
  • Click the role’s name.
  • Click the Users column on the role’s row.
  • Open the row’s action menu (⋮) and select Assign users.
3
Tick the members who should hold the role and untick anyone who should no longer hold it. Use the search box to filter by name or email.
4
Click Save. The role’s assignee list is replaced with your selection: newly ticked members are added, unticked members are removed.
Predefined roles are read-only in this dialog. To change a member’s predefined role, edit the member from the Users tab.

​
Filtering users by role

On the Users tab, use the role dropdown next to Invite New Member to filter the list by role. The dropdown groups roles into Predefined and Custom. Selecting a role narrows the list to members assigned to it; selecting All roles clears the filter.

​
Editing or deleting a role

  • Predefined roles cannot be modified or deleted.
  • Custom roles can be edited at any time. Changes apply immediately to every member assigned to the role; you do not need to re-invite anyone.
  • A custom role can be deleted only after every member has been unassigned from it. If you try to delete a role that still has assignees, the UI returns an error listing how many members still use the role.

​
API reference

The custom roles API is exposed under /api/v2/custom_roles. All endpoints require an account-scoped API key for an Owner or Admin.

​
List roles

The response includes both the global predefined roles and any custom roles defined on the account, so the same payload powers the Roles list page and the Assigned Roles picker.

​
Create a custom role

This example creates a package-group-scoped editor for a single package group, with no connection access. The API still uses the legacy workspace_scope / workspace_ids field names and the *Workspace permission keys:
The scope fields accept all, specific, or none. When the scope is specific, the matching workspace_ids or connection_group_ids array lists the resource IDs to grant access to.

​
Update a custom role

​
Delete a custom role

Returns 422 if any member is still assigned to the role; unassign them first and retry.

​
Assign custom roles to a member

Pass custom_role_ids to the members endpoint when inviting or updating a member:
Passing an empty array clears every custom role from the member; their predefined role (if any) continues to apply on its own. You can also invite a new member with only a custom role by sending role: "base" alongside a non-empty custom_role_ids array. The invitee’s permissions come entirely from the assigned custom roles. No predefined-role grants apply.

​
Assign members to a role in bulk

Use the role-level members endpoint when you want to manage a role’s assignees from the role itself rather than editing every member individually. It replaces the role’s current assignees with the supplied user_ids list. Missing IDs are added and IDs no longer in the list are removed.
Behavior:
  • The request is idempotent. Sending the same user_ids list twice is a no-op.
  • Passing an empty array unassigns every member from the role.
  • IDs that do not belong to the account are silently ignored, so a stale ID cannot leak members from another account into the role.
  • The endpoint is available only for account-scoped custom roles. Attempting to change the assignees of a predefined role returns 422.
  • The caller needs the manage_member_roles permission (Owner or Admin, or a custom role that grants it).

​
Filter members by role

GET /api/v2/members accepts two optional filters that compose with AND semantics: Send custom_role_id on its own to list every member assigned to that custom role. Send both to list members who hold the given predefined role and the given custom role.

​
Permission reference

The permission keys you can include when building a custom role, grouped by domain: A few permissions are easy to confuse:
  • createJob is the permission to run an existing package (start a new job run). It does not grant the ability to edit the package.
  • updatePackage is the permission to edit a package’s flow. Grant both createJob and updatePackage when an editor also needs to trigger runs.
  • createPackage is the permission to create a new package. It does not imply updatePackage on packages someone else created.
  • manageConnectionAccess is the account-level permission to bind a package group to specific connection groups (see Restricting a Package Group to specific Connection Groups). updateWorkspace alone does not grant it, so a package-group editor cannot change which connections the group’s members can reach.

​
FAQ

Why don’t I see the Roles tab? Custom roles are opt-in. If the Roles tab is missing from Settings > User Management, contact Support to enable them on your account. Can I edit a predefined role? No. Predefined roles (Owner, Admin, Operator, Editor, Reader) are fixed. If you need a variation, build a custom role with the permissions you want. What happens if I remove a permission from a role that’s already assigned to members? The change applies immediately. Members assigned to the role lose the removed permission on their next request. You do not need to re-invite anyone. Can a member be in more than one custom role? Yes. Effective permissions are the union of every custom role the member is assigned, plus their predefined role (if any). What if I assign a custom role that covers fewer permissions than the member’s predefined role? The predefined role keeps applying. Custom roles only add permissions; they never subtract. To restrict a member, lower their predefined role first (for example, set it to Reader), then assign the custom role. Why can’t I delete a role? A role can be deleted only after every member is unassigned from it. Open the role’s row, remove its assignees, and retry the delete.

User Management

Managing Account Members

Setting Account Member Roles

Connection Groups

Last modified on July 14, 2026