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:
ScopeEffect
All package groups / All connection groupsThe role applies to every package group or connection group in the account, including ones created after the role was saved.
Specific package groups / Specific connection groupsThe role applies only to the package groups or connection groups you select. Resources outside that selection are invisible to the role.
No package groups / No connection groupsThe role grants no access in that domain. Members assigned to the role see no resources in that domain at all, including resources that have no group assigned (orphans). Permissions tied to that domain are also hidden from the member’s effective permission set.
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:
Member’s rolesEffective permissions
Predefined role onlyThe predefined role’s permissions, unchanged.
Custom role(s) onlyThe union of every assigned custom role.
Predefined role plus custom role(s)The union of the predefined role’s permissions and every assigned custom role (additive). The predefined role’s account-wide grants still apply, so adding a custom role can only ever grant more access, never restrict it.
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:
PresetUse when
ReaderRead-only access. The role can list and view resources in its scope but cannot make changes.
EditorView and edit. The role can update packages and package groups in scope. Connection access is view-only.
OperatorEdit, run, and manage. The role adds connection management and the ability to run jobs on top of Editor.
CustomPick individual permissions. The checkboxes become editable so you can build any combination.
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.

​
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

curl -u API_KEY: \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "X-Account-Id: ACCOUNT_ID" \
  https://api.integrate.io/api/v2/custom_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: 
curl -u API_KEY: \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: ACCOUNT_ID" \
  -X POST \
  -d '{
    "name": "Analytics editor",
    "description": "Edit packages and run jobs in the analytics package group",
    "permissions": [
      "listWorkspaces", "viewWorkspace",
      "listPackages", "viewPackage", "updatePackage", "validatePackage",
      "listJobs", "viewJob", "createJob"
    ],
    "workspace_scope": "specific",
    "workspace_ids": [123],
    "connection_group_scope": "none"
  }' \
  https://api.integrate.io/api/v2/custom_roles
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

curl -u API_KEY: \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: ACCOUNT_ID" \
  -X PUT \
  -d '{ "permissions": ["listPackages", "viewPackage"] }' \
  https://api.integrate.io/api/v2/custom_roles/ROLE_ID

​
Delete a custom role

curl -u API_KEY: \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "X-Account-Id: ACCOUNT_ID" \
  -X DELETE \
  https://api.integrate.io/api/v2/custom_roles/ROLE_ID
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: 
curl -u API_KEY: \
  -H "Accept: application/vnd.xplenty+json; version=2" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: ACCOUNT_ID" \
  -X PUT \
  -d '{ "custom_role_ids": [42, 57] }' \
  https://api.integrate.io/api/v2/members/MEMBER_ID
Passing an empty array clears every custom role from the member; their predefined role (if any) continues to apply on its own.

​
Permission reference

The permission keys you can include when building a custom role, grouped by domain:
DomainPermissions
Package groups (workspaces)listWorkspaces, viewWorkspace, createWorkspace, updateWorkspace, deleteWorkspace
PackageslistPackages, viewPackage, createPackage, updatePackage, deletePackage, validatePackage, listPackageTemplates
JobslistJobs, viewJob, createJob, updateJob
ScheduleslistSchedules, viewSchedule, createSchedule, updateSchedule, deleteSchedule
ConnectionslistConnections, viewConnection, createConnection, testConnection, importConnection, updateConnection, deleteConnection
Connection groupslistConnectionGroups, viewConnectionGroup, createConnectionGroup, updateConnectionGroup, deleteConnectionGroup
ClusterslistClusters, viewCluster, createCluster, updateCluster, deleteCluster
MemberslistMembers, viewMember, createMember, updateMember, deleteMember, updateMemberRole
HookslistHooks, viewHook, createHook, updateHook, deleteHook
Global variablesviewGlobalVariables, updateGlobalVariables, viewGlobalSecrets, updateGlobalSecrets
AccountviewProfile, updateProfile, viewUsage
BillingviewBilling
DeveloperviewApiKey, regenerateApiKey, listConnectedApplications, manageConnectedApplications
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.

​
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 June 23, 2026