Role Builder

Updated 2 years ago by admin

The Role Builder allows you to define custom access to the dashboard using ACL-style permissions and share the defined roles with other accounts. This advanced section allows fine grained control to be delegated to administrators, however for a faster start you can use any of the pre-defined Roles instead.

To access the Role Builder, navigate to the Products -> Role Builder option in the primary menu.

This will open the Roles and Permissions panels.

You can create a new role in one of two ways:

  • By creating the role and its permissions manually
  • By importing a previous exported role

Creating a new Role manually

To create a new role and add permissions manually, click the + button in the top right of the Roles panel and type the desired name for the new role in the text box.

Click Update to add the role.

As this is a new role, it will contain no permissions.

Assigning an empty role to an administrator will provide basic permissions to enable them to log in and change their password, or access any available End User features that may be enabled.

Click the Edit (pencil) icon in the top right panel of the Permissions panel to start adding permissions to the role.

The dashboard has many different permissions (ACL's) and some permissions depend on others in order to make a section of the dashboard fully accessible. To try and simplify the complexity, permissions have been organised into logical ACL groups and dependencies will automatically be added if there are any. This means, often selecting a generic permission such as MFA Setup will add multiple permissions to enable activating MFA and verifying the token, so that you do not have to do this manually.

Permissions essentially map to API endpoints that the dashboard, a Single Page Application, calls when the user performs actions. Every permission can potentially support a Read (e.g. view), Create (e.g. add new), Update or Delete action. If the permission does not support a particular action then it will be disabled.

For example, if you wanted to allow another user to only view and update other Administrators, you would select the Read and Update actions of the Manage Administrators permission only.

In the above example, in order to be able to view administrators the ability to view Roles is also required. This dependent permission will automatically be added.

Dependent permissions will likely expose additional sections of the dashboard but they will only inherit the actions from the dependency.

Once permissions have been added to the role, the Group that they belong to will indicate the permission is active with an orange tick and the permission itself will show a green tick.

If only some of the permissions in a group are active in the role, the group level indicator will show an orange tick. If all permissions in a group are active in the role, the group level indicator will change to a green tick. A red cross indicates the permission is not active in the role. If a group has no active permissions, the group level indicator will be a red cross. This lets you quickly identify which ACL groups are active in the role.

After adding or removing permissions to a role, the user must log out and log back in again to see the change.

Follow this pattern to build the custom role that you require. For further information, see the Tips & Troubleshooting section at the end of this article

Once you have finished adding permissions, click the cross X icon in the top left of the Add/Remove Permissions panel to close the editor.

Importing or Exporting Role


Once you have built a role, if you wish to export this for use in other accounts, you can click the Export icon next to the role name in the Roles panel. This will create a Role Data string which you can copy to the clipboard.

The Role Data string is only valid whilst the role still exists.

It is possible to use the export option to transfer roles to child accounts or create copies of existing roles. See the section on Importing for more information.


You will need to obtain a Role Data string by first exporting a role or being given the string by your Service Provider.

Click the Import button and paste the Role Data string into the Import Role dialog and then click Import.

If the role already exists in the current account, you will be prompted to select the preferred action:

  • Rename - this will create a new version of the role with a different name, preserving the existing role
  • Overwrite - this will simply overwrite the role with the imported role
The role must exist that you are importing. Deleted roles cannot be re-imported.

Tips & Troubleshooting

Creating a Report Viewer role

Reports, specifically the Activity reports, require read-only access to ACL's that are also used for Product configuration/management. For example, the ability to search the report by Device Group, requires the "read" permission for the Device Groups ACL. This will automatically provide read-only access to the Device Groups list in the dashboard unless you use special ACL's to force "Reports Only" access. To do this, after building the role, add one or more of the following special ACL's to the role:

This will ensure that the dependent ACL's do not generate options in the Products menu.

The menu option is available but nothing happens when it is clicked

This problem is most likely to manifest when a dependent ACL/permission is missing. Access has been granted to the UI section however it is calling an API endpoint that is missing a permission in the role.

To confirm this, press F12 to open the browser Development Tools (Chrome, Edge, Firefox) and then navigate to the Network sub-tab, then recreate the issue.

Search for any requests which are highlighted in red with a 403 error code, e.g.

View the request and make note of the URL, it will have the format:[endpoint]

In the above example, the endpoint is /enduser/email-securemail/sso/generate_token

Search the ACL Groups for the human readable form of the endpoint, e.g. "Token" and then search for the corresponding permission. In this case, it is the SecureMail end-user token. Add this permission with Read access to the role in order to solve the problem.

How did we do?