> This page is for Portal.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emnify.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emnify.com/_mcp/server.

> Build a role with an exact set of permissions when the built-in system roles grant too much or too little access

The [system roles](/portal/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](/portal/workspaces/manage-users), so you assign them the same way.

> **Note**
>
> 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.

> **Note**
>
> **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**.

> **Info**
>
> **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.

| Field       | Required | Rules                                                                                                                                                                                                                                                            |
| :---------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name        | Yes      | Unique in the Workspace. 2 to 50 characters. Letters without accents (`A`–`Z`), numbers, spaces, dashes (`-`), underscores (`_`), ampersands (`&`), apostrophes (`'`), and parentheses (`(` and `)`). Other characters, such as `é`, `%`, and `$`, are rejected. |
| Description | No       | 2 to 250 characters.                                                                                                                                                                                                                                             |

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.

| Category                  | Group                  | Covers                                                   |
| :------------------------ | :--------------------- | :------------------------------------------------------- |
| Connectivity & operations | Devices & SIMs         | Devices, SIMs, eSIMs, quotas, and connectivity.          |
| Connectivity & operations | Policies               | Service policies, coverage policies, and firewall rules. |
| Connectivity & operations | Automations            | Event log and automation rules.                          |
| Data & integrations       | Integrations           | External systems, data streams, and secure connections.  |
| Data & integrations       | Insights               | Dashboards and reports on connectivity and usage.        |
| Workspace settings        | Organization & billing | Company details, billing, payments, and single sign-on.  |

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](/developers/api-guidelines/manage-permissions).

> **Info**
>
> 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](/developers/api-guidelines/manage-permissions).