Roles Management

This article describes how to manage the user roles in tenant.

• Roles and permissions
• Available user roles
• Custom user roles
  • Request structure parameters
  • Example role structure
• Available Permissions

You can view the user roles in the tenant using the TenantAdmin account. However, to edit the user roles you must use dedicated service account.

Roles and permissions

A role in the platform is an attribute that is defined with a set of permissions enabling it to perform operations on the platform. There are different types of roles in the platform:

• Service accounts - These are specific roles with set permissions to perform specific operations with system infrastructure and services. Details of these roles and permissions presented elsewhere. This article would not extend on these accounts and permissions.
• TenantAdmin - This role has defined permissions to operate the tenant specific entities.
• User roles - These are attributes that have set of defined permissions for the users to perform operations on the platform.

Available user roles

The platform has default set of user roles which have already defined permissions to perform operations in contracts and workspaces. The details of abilities for user roles in context of contract and workspace units are presented elsewhere. Here we will list the roles in conjunction with their permissions.

Contract roles are (click to expand to see the permissions):

Workspace roles are (click to expand to see the permissions):

The contract.owner and workspace.owner roles are part of the platform core functionality. Your attempts to edit or delete these roles will fail. You can edit or delete all the other roles, even create your own versions (using the service account).

Custom user roles

You can create, edit and delete custom user role within the context of contract or workspace using a special Service account role. There are a few restrictions for custom role creation and role deletion:

• You cannot create more than one role with identical names in one scope,
• You cannot delete a role that is assigned to a member,
• You cannot delete contract.owner and workspace.owner roles,
• You cannot delete a role that is used during the contract creation.

To create, edit or delete a user role follow these instructions:

1. Use HTTP GET call to the platform API /v2/tenants/{TENANT_ID}/roles endpoint using the TenantAdmin credentials to get the current list of roles and permissions. More about this API call here.
2. Examine the returned JSON structure and make your modifications following the established structure and the example case.
3. Use the HTTP PATCH call to the platform API /v2/tenants/{TENANT_ID}/roles endpoint using the service account credentials to add, modify or delete a role. The TENANT_ID in the call is the ID of tenant where the modification must be done. More about this API call here. Don’t submit the tenant id, relationships and meta parts you got in the step 1 back in the body of the call.

Before you go and try to modify the tenant roles table you must remember to submit all existing roles along with the new modifications in one API call. Failure to do so can cause disruptions for all user operations in your tenant.

Request structure parameters

Below are request parameters:

Example role structure

As an example we would like to create an Operator role in workspaces with the follwing abilities:

• To be able to start/stop flows (workspaces.flow.toggleStatus),
• To be able to edit or create credentials for integration steps (workspaces.credential.edit),
• To be able to change the flow from ordinary to real-time and back (workspaces.flow.toggleRealtime),
• To be able to access auth_secrets in the workspace (workspaces.auth_secret.get),
• To be able to access globally defined auth_clients (global.auth_clients.get),
• To be able to read credentials associated with auth_secrets (workspaces.auth_secret.get_credentials),
• To be able to manually trigger auth_secret refresh procedure (workspaces.auth_secret.refresh),
• To be able to access all logs of the workspace (workspaces.logs.read_all).

Here is the part of json to include in your API call to grant the permissions:

 {
   "data" : {
     "type" : "tenant-policy",
     "attributes" : {
       "roles" : [
         {
           "i18n" : {
             "en" : "Operator"
           },
           "role" : "operator",
           "permissions" : [
             "workspaces.flow.toggleStatus",
             "workspaces.credential.edit",
             "workspaces.flow.toggleRealtime",
             "workspaces.auth_secret.get",
             "global.auth_clients.get",
             "workspaces.auth_secret.get_credentials",
             "workspaces.auth_secret.refresh",
             "workspaces.logs.read_all"
           ],
           "scope" : "workspaces"
         },
         { "role 2" },
         { "role 3" },
         { "etc roles "}
       ]
     }
   }
 }

Available Permissions

This section presents permissions available to the platform users. These permissions are set for 3 different levels like global, contracts and workspaces.

• global - these permissions have tenant-wide reach
• contracts - these permissions are set for contract wide operations
• workspaces - these permissions are set for workspace operations

These are not all permissions available in the system. There are additional group of permissions not available for users for performing specific operations with the system infrastructure and services.