Custom roles
The system roles cover most teams, but each one grants a fixed set of permissions that you can’t change. A custom role lets you choose the exact permissions a role grants, so someone can work in one area of the emnify Portal without gaining access to the rest.
Custom roles sit alongside system roles. They appear in the User role list when you invite a user or change a user’s role, so you assign them the same way.
Custom roles are in beta and aren’t available in every Workspace yet.
Who can manage custom roles
Creating, editing, duplicating, and deleting custom roles requires the Administrator role.
SuperAdmin isn’t one of the system roles. It’s a layer on top of a user’s existing role, so a SuperAdmin can do everything an Administrator can.
Where to find custom roles
Custom roles are on Workspace settings > Roles, which lists every role in the Workspace.
Each card shows the role name, its description, and how many users and application tokens are assigned to it.
The tab has two parts:
- System role lists Administrator, User, and Observer. These cards are informational. System roles are predefined and can’t be edited or deleted.
- Custom role lists the roles your Workspace created. Each card opens the role for editing, and its Quick actions menu offers Edit, Duplicate, and Delete.
Delete is only available for a custom role that has no users or application tokens assigned to it. Move those assignments to another role first.
A Workspace can hold a limited number of custom roles. After you reach the limit, New custom role and Duplicate are turned off, and you have to delete an existing role before you can create another.
Role names and descriptions
Every custom role needs a name. The description is optional, but it’s the only place to record who a role is meant for, so it’s worth filling in.
Name a role after the job it covers rather than the person doing it.
How permissions are organized
The role form arranges permissions by area of the Portal, from broad to specific:
- Categories, such as Connectivity & operations, gather related groups.
- Groups, such as Devices & SIMs, cover one area of the Portal.
- Sections, such as View devices, split a group into what a role can see and what it can change.
- Sets of permissions, such as Device table, bundle the permissions that one part of the Portal needs. Expand a set to see its individual permissions.
- Individual permissions, such as View device list, are single checkboxes.
Every permission starts switched off, so a custom role grants nothing until you turn permissions on. Each group and section shows how many of its individual permissions are active. On larger screens, a permissions overview next to the form shows the number of active permissions in total and for each group, and selecting a group in the overview takes you to it. On smaller screens, only the total appears.
Some sets of permissions, such as Transfer SIMs, Delete devices and SIMs, and Single sign-on (SSO), carry a Critical access badge because they allow sensitive actions that can cause serious problems if misused. Review these carefully before you grant them.
If a role also has permissions assigned through the API that the form doesn’t list, an Additional API-managed permissions alert appears when you edit or duplicate it. The form doesn’t show those permissions, and they stay active when you save, so change them through the API.
The Roles tab and the emnify API list the same roles, so a custom role you create through the API appears here too. To build one through the API instead, see Manage roles and permissions.