Permissions

Almost every request to the emnify API is authorized against a single permission. A few endpoints need none: public ones such as authentication, and a handful that only require a signed-in user. If your role doesn’t include the permission an endpoint requires, the API responds with 403 Forbidden.

Each endpoint’s required permission is shown in a callout at the top of its reference page. For endpoints that require no permission, such as authentication, the callout says so. For every permission at once, and the roles that include it, see the permission reference.

How permissions work

A permission is a pair of a resource (the thing you act on) and an action (what you do to it). In these docs it’s written as Resource + Action, for example Endpoint + List. You always need the exact pair.

Permissions are grouped into roles, and every user is assigned a role:

• System roles are built in and can’t be edited: Administrator, User, and Observer. Each includes a fixed set of permissions.
• Custom roles let you grant an exact set of permissions that you choose.

To call an endpoint, your role must include that endpoint’s required permission.

Roles and permissions documents what each system role includes in the emnify Portal. A custom role grants whatever combination you choose.

The permission model

System roles

To grant a different combination, create a custom role from the permissions in the reference below. For ready-made permission sets covering three common jobs, see Role templates.

Permission reference

The table lists each API permission and which system roles include it.