Managing user roles in a contract

This document explains what roles and permissions are, how roles are set in the UI and how custom roles are configured. Additionally, it provides a list of non-deletable roles, and a permissions reference table.

Roles and permissions

A tenant admin can control user rights in his tenant by configuring user roles. A role is a user attribute that defines a set of permissions for the user. Contract roles define permissions for contract management, and workspace roles define permissions for workspace management.

The default contract roles are:

  • Owner. Users with this role can edit contract members list, create and delete workspaces, and see all workspaces in the contract.

  • Admin. Users with this role create and delete workspaces, see all workspaces in the contract, make changes into repository, and edit development team.

  • Member. Users with this role can create workspaces in the contract.

The default workspace roles are:

  • Owner. Users with this role can edit the workspace, edit flows, toggle flows’ active/inactive status, toggle flows’ real-time/ordinary status, and edit workspace credentials.

  • Admin. Users with this role have the same permission set as Owner.

  • Integrator. Users with this role can edit flows, toggle flows’ active/inactive status, toggle flows’ real-time/ordinary status, and edit credentials.

  • Guest. Users with this role can browse the workspace.

Note that a full set of contract permissions does not automatically mean a full set of permissions for every workspace. A contract Admin may be a Guest in a certain workspace.

Setting user roles

The owner or admin sets roles individually for each user when adding users to the workspace or contract. Also, the admin can edit roles of existing members in the contract or workspace.

To set a role for a user when adding or inviting new users to a workspace:

1. Open Workspace in navigation menu and click Edit member’s role:

Workspace - navigation menu

2. Either add or invite a new member:

a) Click Add new member, select an existing user and use the Role dropdown menu.

Add new member - role

b) You can invite new member in your workspace only if your Contract Role is Owner. Click Invite new member, enter user email and use Contract Role and Workspace Role dropdown menus. In the corresponding menu, select the required role. If your tenant has an extensive list of roles, use the Find role field to optimize search. Start typing to gradually filter out unwanted roles.

Invite new member

5. Click Send Invite to finish.

Invite new member - send invite

To set a role for a user when adding or inviting new users to a workspace:

1. Edit member’s roles In the Members tab:

Edit member’s roles

4. Alternatively, invite a new member and set the roles. Initially, only Contract Role dropdown menu is visible. To assign the new member’s workspace and workspace role, click Specify invitee’s workspace, and use the Workspace Role dropdown menu. Then click Send Invite.

Members - invite new member

Configuring custom user roles

A tenant admin can configure custom roles if required. To do that, the admin needs a special set of credentials called service account. It can be acquired by an authorized client employee via support.

There are a few restrictions for custom role creation and role deletion:

  • You cannot create multiple roles with identical names in one scope;
  • You cannot delete a role that is assigned to a member;
  • You cannot delete essential roles;
  • You cannot delete a role that is used in contract.availableRoles (learn more about it here).

When the tenant admin uses the service account privileges, he can create custom roles via the following API request:

PATCH{TENANT_ID}/roles , where

{TENANT_ID} parameter stands for the ID of the tenant.

Below are request parameters:

Payload Parameter Required Description
type yes This parameter should have the value: tenant-policy
attributes.roles[] yes An array of Tenant’s roles. It can be empty.
attributes.roles[].role no Custom role name
attributes.roles[].scope no The group of objects, which is affected by this role. Value can be: contracts or workspaces.
attributes.roles[].permissions[] yes An array of permissions. It can be empty. To get the list of available permissions execute the endpoint: GET or see this reference table.
attributes.roles[].i18n. no The name of a role in different languages. The value is only required for en key. For other languages value is optional.


To add a new role called Godzilla, with permissions to see and delete workspaces in the contract, and edit a workspace, we will use the following request:

   -u {EMAIL}:{APIKEY}
   -H 'Content-Type: application/json' -d '

NOTE: these endpoints are still in development and are subject to change.

Essential roles

A number of roles cannot be edited or deleted, because their functionality is unique. They are:

  • contract.owner - this role is assigned to the first member of the contract;
  • workspace.owner - this role is assigned to the user who created the workspace;

These roles have exclusive permissions, which are essential for contract and workspace management.

Permissions reference table

Permission Description
contracts.membership.edit Edit members in the contract
contracts.workspace.create Create workspaces in the contract
contracts.workspace.listAll View all workspaces in the contract
contracts.workspace.delete Delete workspaces in the contract
contracts.repository.edit Edit contract repository
contracts.devTeam.edit Edit developer team
workspaces.workspace.edit Edit the workspace
workspaces.flow.edit Edit flows in the workspace
workspaces.flow.toggleStatus Toggle flow status between active and inactive
workspaces.flow.toggleRealtime Toggle flow status between ordinary and real-time
workspaces.credential.edit Edit credentials