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. Clusters and hooks are set in the Access Level grid, the others under Global Permissions. 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.
If a role is scoped to Specific package groups and the last package group in that scope is deleted, the scope is automatically demoted to No package groups. This is deliberate: a role with an empty Specific list would otherwise grant access to every package group in the account. Edit the role to add new package groups to its scope, or delete the role, once you notice the demote.

​
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 manage schedules).

​
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. The Update permission for packages also lets members use Import/Export in the package designer when Source Control is enabled on the account. See Import or Export Package JSON.
Role creation form with the Operator preset selected and Specific scope chosen for one package group and one connection group

​
Permissions needed to run a package

Running a package needs both of these permissions:
  • Create under Jobs (createJob) starts a job for a package in the role’s package groups.
  • Update under Clusters (updateCluster) is needed because every job runs on a cluster, and the run is checked against that cluster too.
The Editor and Operator presets include both. In a Custom role, tick both. A role with Create under Jobs but only List and View under Clusters still shows the Run Job button, but the run fails with “You don’t have permission to perform this action”. Cluster permissions apply to every cluster in the account, whatever the role’s package group scope. Update under Clusters also lets members edit and terminate clusters. To let members start a new cluster from the Run Job dialog, also tick Create under Clusters.

​
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, pick the member’s roles. The card has two groups:
  • Predefined role: select one option. A member can hold at most one predefined role. Select None to give the member custom roles only. None is the default when you invite a new member.
  • Custom roles: tick any number of custom roles. This group only appears when your account has custom roles.
You can combine a predefined role with one or more custom roles, or assign custom roles on their own. When you edit a member, their current predefined role is already selected and all of their custom roles are already ticked.
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. Starting a run also needs updateCluster; see Permissions needed to run a package.
  • updatePackage is the permission to edit a package’s flow. When an editor also needs to trigger runs, grant createJob and updateCluster as well.
  • 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.
  • viewAiApiKey is the permission to use the account’s AI API key. The AI Transformation component reads that key when its editor opens, so without this permission a member sees a notice asking them to contact an admin instead of the Managed Key option. They can still build the component with their own key. Grant this to anyone who should use the account’s key.
  • manageAiApiKey is the permission to provision, replace, or delete that key. It is separate from viewAiApiKey because provisioning creates a billable credential and replacing one invalidates the key already saved in existing packages. Grant viewAiApiKey on its own for pipeline builders, and add manageAiApiKey only for people who should control the credential itself.

​
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. Why can’t a member on a custom role use the account’s AI API key? The role is missing viewAiApiKey. In the AI Transformation component they see a notice asking them to contact an admin, in place of the Managed Key option. Two cases cause this. Custom roles never inherit permissions from the predefined roles, so a role created before this permission existed will not have picked it up. And building a role from the Operator or Editor access level preset does not include it either, because those presets only pre-fill the resource permission grid, while account-level permissions such as the AI ones are picked separately under Global Permissions. In both cases, edit the role and tick Use the account’s AI API Key under AI Features. Members on the predefined Owner, Admin, Operator, or Editor roles already have it and need no change. 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. Why does a member get “You don’t have permission to perform this action” when running a package? Their role most likely has Create under Jobs but not Update under Clusters. Running a package needs both, so the Run Job button shows but the run is rejected. Edit the role and tick Update under Clusters. See Permissions needed to run a package. 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 October 27, 2026