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

> Instructions for how to create, edit, duplicate, and delete custom roles with a specific set of permissions in the emnify Portal

To create and manage custom roles, go to **Workspace settings** > **Roles**.

> **Note**
>
> Custom roles are in beta and aren't available in every Workspace yet.
> For what a custom role grants and how its permissions are organized, see [Custom roles](/portal/roles/custom).

## Create a custom role

On the **Roles** tab, click **New custom role**.

> **Info**
>
> If your Workspace doesn't have any custom roles yet, click **Add custom role** in the empty **Custom role** panel instead.
> Both open the same form.

Click the edit icon next to **Name user role** and enter a name.

The name must be unique in the Workspace and 2 to 50 characters long.
It can contain letters without accents, numbers, spaces, dashes, underscores, ampersands, apostrophes, and parentheses.
Any other character produces a formatting error.

Optionally, click the edit icon next to **Add description** and describe the job this role covers.

The description must be 2 to 250 characters.

Expand each [group](/portal/roles/custom#how-permissions-are-organized) the role needs, then choose permissions in its sections.
Select a set of permissions to grant all of it, or expand the set and select individual permissions.

Every permission starts switched off.
Counters on each group and section, and the total in the permissions overview, show how many permissions are active.

Review your selections, then click **Create**.

> **Check**
>
> A success notification appears and the new role is listed under **Custom role** on the **Roles** tab.

To give the role to someone, select it as their **User role** when you [invite a user or change a user's role](/portal/workspaces/manage-users).

## Edit a custom role

On the **Roles** tab, click the custom role's card.
You can also open **Quick actions** on the card and select **Edit**.

In **Edit user role**, change the name, description, or permissions.
The same [name and description rules](/portal/roles/custom#role-names-and-descriptions) apply as when you create a role.

> **Info**
>
> If an **Additional API-managed permissions** alert appears, the role also has permissions assigned through the API that the form doesn't list.
> They stay active when you save, so change them [through the API](/developers/api-guidelines/manage-permissions).

Click **Save**.

> **Check**
>
> A success notification appears and the role's card shows the updated name and description.

## Duplicate a custom role

Duplicating copies an existing custom role into a new one, so you can start from a similar set of permissions instead of an empty form.

On the **Roles** tab, open **Quick actions** on the card of the custom role you want to copy, then select **Duplicate**.

> **Info**
>
> **Duplicate** is turned off when your Workspace reaches its custom role limit.
> Delete a role first to free up space.

In **Duplicate user role**, review the form, which is already filled in.
The name is the original name followed by `(copy)`, and the description and permissions are copied from the original role.

> **Info**
>
> If an **Additional API-managed permissions** alert appears, the role also has permissions assigned through the API that the form doesn't list.
> They stay active when you save, so change them [through the API](/developers/api-guidelines/manage-permissions).

Change the name and adjust the permissions as needed.
The name must still be unique and no longer than 50 characters, including the `(copy)` suffix if you keep it.

Click **Create**.

> **Check**
>
> A success notification appears and the new role is listed under **Custom role** on the **Roles** tab.

## Delete a custom role

You can't delete a system role.
**Delete** is only offered on custom role cards.

On the **Roles** tab, find the custom role you want to delete and open **Quick actions** on its card.

Select **Delete**.

> **Info**
>
> **Delete** is turned off for a role that still has users or application tokens assigned to it, and an info icon explains why.
> Reassign them to another role first, then delete the role.
> For users, see [Modify a user's role](/portal/workspaces/manage-users#modify-a-users-role).

Review the confirmation, then click **Delete role**.

Deleting a role can't be undone.

> **Check**
>
> A success notification appears and the role is removed from the **Custom role** list.