Manage roles and permissions
Most endpoints of the emnify REST API require a specific permission, which is a pair of a resource and an action. A few require none, such as authentication. The three system roles (Administrator, User, and Observer) cover common access patterns, but they can’t be edited. To grant an exact set of permissions, create a custom role and assign it to users.
This guide shows how to manage roles and permissions via the API:
- List the permissions available to your Workspace.
- Create a custom role.
- Update the permissions of a custom role.
- Assign a role to a user or remove it.
- Check your own permissions.
Before you begin
All requests require an authentication token. Managing roles and users requires a role that includes the user and role management permissions, such as Administrator.
In these requests, orgId accepts either a numeric Workspace ID or the literal my, which targets your own Workspace.
Use a numeric ID when you administer a child Workspace.
List available permissions
To see every permission you can assign, request the permission catalog:
Each entry pairs a resource with an action and lists the API routes that the permission guards under entrypoints:
A permission with a non-null deprecated_at timestamp is end-of-life.
It still appears in the catalog so that existing roles keep working, but you can’t add it to new or updated roles.
Every endpoint’s reference page shows its required permission in a Required permissions callout.
Select Copy JSON in the callout to copy the permission pair as JSON, ready to paste into the permissions array used below.
Create a custom role
During the beta, a Workspace can hold at most 3 custom roles. To request beta access, contact your Customer Success Manager.
Create a role by giving it a unique name and the set of permissions it grants. List only what you want to grant: anything you leave out is denied.
The response is 201 Created with the new role and its resolved permission list:
Instead of resource and action pairs, you can pass numeric permission IDs from the catalog as permission_ids.
The two fields are mutually exclusive: supplying both returns 400 Bad Request.
Constraints:
- Role names must be unique within the Workspace and 2 to 45 characters.
- Role names accept letters, digits, spaces, and
_,-,&, and'. Any other character returns400 Bad Request. - A Workspace can have at most 50 custom roles.
Update a role’s permissions
Update a custom role with a partial PATCH: only the fields you send change.
Sending permissions (or permission_ids) replaces the role’s existing permission list.
Include every permission the role should keep, not only the ones you’re adding.
System roles can’t be modified or deleted. To retire a custom role, delete it once no users are assigned to it:
Assign a role to a user
List your roles with their IDs first, if you don’t know them:
Then assign a role to a user by ID:
A successful assignment returns 204 No Content.
To remove a role from a user, send DELETE to the same path.
A user always keeps at least one role: removing the last remaining role returns 409 Conflict.
Check your own permissions
To verify what your token can do, list the permissions granted by all of your roles in the current Workspace:
Troubleshooting
For how permissions work and which permissions each system role includes, see Permissions. For ready-made permission sets covering three common jobs, see Role templates.
Role changes raise system events, so you can audit who created, edited, or deleted a custom role, and when a user’s role changed. See User management events.