> Source: https://builder.ema.ai/v2/administration/custom-roles
> Title: Custom Roles

# Custom Roles

A custom role is a role your workspace makes for itself. Ema's built-in roles, such as Builder and User admin, may not fit how your team works. A custom role lets you give people exactly the permissions they need, and no more. You choose the role's scope and its permissions, and you assign it the same way as a built-in role.

> [INFO]
> **Availability.** Custom roles are turned on for each workspace. Group and AI Employee custom roles are turned on separately. If you don't see the controls on this page, ask your Ema representative.

## Before you start

-   Read [Governance and permissions](/builder/v2/administration/governance-and-permissions). It explains the built-in roles and the permission names, such as `workflow.publish`.
-   Roles live on the **Roles** tab. Select **Settings**, then **User Management**, then **Roles**.

## Who can manage custom roles

Four permissions control custom roles:

Permission

What it lets you do

Built-in roles that hold it

`role.view`

Open the Roles tab and read every role, its permissions and its users.

System admin, User admin

`role.create`

Create a role, clone a role, and import a role from a file.

System admin

`role.edit`

Change a role, save a draft, publish, discard a draft, disable and enable.

System admin

`role.delete`

Delete a custom role.

System admin

A custom role can also hold these permissions. Then the people who have it can manage roles too. A person who can read roles but not change them sees a note that says so.

Two rules stop anyone from giving more access than they have:

-   **You can only add a permission you hold yourself.** You can't select a permission you don't hold. You also can't choose a level that would add one.
-   **To change a role, you must hold every permission it grants.** This applies to every change: edit, publish, discard, disable, enable and delete. If you don't, the app says "You can't change this role" and names the permission you are missing.

## Role scopes

Every role has a scope. The scope decides where you assign the role and what it applies to. You choose the scope when you create the role. You can't change it later.

Scope

Applies to

Where you assign it

Built-in roles in this scope

**Workspace**

The whole workspace. Each person has one workspace role.

**Settings → User Management**, when you invite someone or edit their role.

User, Builder, User admin, System admin

**Group**

One group and the resources it owns.

The group's **Permissions** tab.

Group Member, Group Builder, Group Admin

**AI Employee**

One AI Employee and its knowledge.

The AI Employee's **Permissions** tab.

AI Employee Guest, Manager, Builder, Admin and User

Group and AI Employee roles never give access across the whole workspace. They add access only on the group or AI Employee where you assign them.

Each scope offers its own list of permissions:

-   **Workspace** roles can use every permission in the catalogue.
-   **Group** and **AI Employee** roles can use a shorter list. It covers AI Employee work (view, run, review, edit, publish, delete and manage access), knowledge bases and documents, run activity and audit, AI Employee metrics (view and edit), evaluations and debug traces. Group roles can also include `group.manage` and `group.edit_metrics`. Ema adds a permission to these lists only after it checks that the permission works on that kind of resource.

Your workspace can have up to 100 custom roles in each scope. Drafts and disabled roles count toward the limit. The Roles tab warns you when a scope is close to the limit.

## The Roles tab

The Roles tab lists your roles in two sections: **Built-in roles** (Ema's) and **Custom roles** (your workspace's). Select a row to open the role.

Column

What it shows

**Role**

The name and description. Under the name, a marker can show **Unpublished changes**, **Ema changed the role this was copied from**, or **Replaces** an Ema role.

**Scope**

Workspace, Group or AI Employee. This column appears when the list shows more than one scope.

**Status**

**Published**, **Draft**, **Disabled** or **Deletion pending**. A built-in role shows **Published**, or **Disabled** if you turned it off in your workspace.

**Users** or **Assignments**

For a workspace role, the number of members who have it. For a group or AI Employee role, the number of assignments. One person can have several assignments, so this is not a count of people.

Use the search box to find a role by name or description. Select **Filters** to narrow the list by scope, by type (built-in or custom) and by status. The toolbar also has **Import role** and **Create role**.

Each row has a ⋯ menu. It offers the actions that apply to that role and that your permissions allow: **Users**, **History**, **Clone**, **Export** and **Delete**. History, Export and Delete are for custom roles only.

## Create a custom role

Creating a role has three steps: role details, permissions, and review.

### Step 1: role details

1.  On the Roles tab, select **Create role**.
2.  Choose the **Role scope**: Workspace, Group or AI Employee.
3.  Enter a **Name** and a **Description**. The description helps people choose the right role when they assign it.
4.  Under **Start from**, choose one:
    -   **Clone a role**. Choose an existing role in the same scope, built-in or custom. The new role starts with its published permissions. The copy is independent of the role it came from. Most roles start here.
    -   **Start from scratch**. The role starts with no permissions. A workspace role always includes standard workspace membership.
    -   **Import role**. Select **Browse files** and choose a role file exported from another workspace. The role starts with the file's permissions.
5.  Select **Continue**.

> [WARNING]
> **Empty workspace roles take access away.** Each person has one workspace role. A workspace role made from scratch doesn't give the chat and AI Employee access that User gives. Most workspace roles start as a clone of User.

### Step 2: permissions

The permissions page shows the same editor as a role's page. It is filled from your starting point. Change the permissions as you need. See [Choose permissions](#choose-permissions). Then select **Review**.

### Step 3: review

The review page shows what the new role grants and how it differs from where it started. Nobody holds the role yet. Then choose one:

-   **Publish** puts the role in force. It appears in the role pickers for its scope, and you can assign it.
-   **Save draft** keeps the role as a draft. It grants nothing, and nobody can be given it, until you publish it.

### Name rules

-   **Name**: what people see when they assign the role. It must be unique among your workspace's roles in the same scope, ignoring case, and it can't match an Ema role. Draft and disabled roles keep their names. A deleted role frees its name.
-   **API name**: Ema makes it from the name. It is used in the API, in sign-in tokens and in the audit log. **You can't change the API name later**, and a deleted role's API name stays reserved.

## Choose permissions

The editor groups permissions into areas, such as **AI Employees**, **Knowledge**, **Integrations**, **Metrics**, **Activity and audit**, **Users, Groups and teams** and **Workspace settings**. Group and AI Employee roles show only the areas their scope offers. Use the search box to find a permission by name or description.

Each area has a row of access levels: **None**, **View**, **Use**, **Edit** and **Manage**. Choose a level to select every permission in that area up to and including that level. Higher levels in the area are cleared. **None** clears the area. The levels also show when the role holds only part of a level. Not every area has every level.

Below the levels, each area lists its permissions. Select or clear one permission at a time to fine-tune the role. Each permission shows a plain description, such as "Publish AI Employee versions" for `workflow.publish`. Hover over it to see its technical name. Permissions that give broad or private access, such as delete permissions, carry a **Sensitive** badge.

> [TIP]
> **Delete permissions are at Manage.** To let a role delete AI Employees or knowledge, give it the **Manage** level in that area, or select the delete permission on its own.

Some rules apply while you choose:

-   **Prerequisites are added for you.** Some permissions only work with another one. For example, most AI Employee permissions need `workflow.view`, and `role.create`, `role.edit` and `role.delete` need `role.view`. When you select a permission, Ema also selects what it needs and marks it **Prerequisite**. A prerequisite stays on while a selected permission needs it. When nothing needs it any more, it is cleared too.
-   **Workspace membership is always included** in a workspace role. You can't remove it.
-   **Only permissions the scope supports can be published.** If a role holds a permission its scope doesn't support, remove it before you publish.

### Example roles

These examples show how teams use each scope.

Role

Scope

Permissions

**Support Analyst**: runs support AI Employees, reads every conversation and reviews metrics.

Workspace

Cloned from User, plus `chat.view_all` and `metrics.view`.

**Regional Lead**: builds and edits a regional group's AI Employees and knowledge.

Group

`workflow.view`, `workflow.edit`, `workflow.publish`, `knowledge_base.edit`, `knowledge_base.add_document`

**Claims Reviewer**: reviews claims that one AI Employee flags for a human decision.

AI Employee

`workflow.view`, `workflow.execute`, `workflow.hitl_review`, `knowledge_base.view`, `knowledge_base.tag_document`

## The role's page

A role's page has two tabs:

-   **Permissions**: what the role grants, area by area.
-   **Users**: the people who have the role. For a group or AI Employee role, it also shows where the role is assigned. You can search the list and export it as a CSV file.

The **⋯ More actions** menu on a custom role offers **Edit details**, **History**, **Clone**, **Export**, **Disable** or **Enable**, and **Delete**, as your permissions allow. Where Autopilot is turned on, **Ask Autopilot** opens Autopilot to help you improve the role's permissions.

## Change and publish a role

A role changes in two steps. You save your changes, then you publish them. People who have the role keep the published version until you publish.

1.  On the role's page, select **Edit**.
2.  Change the permissions. The footer counts the permissions you added and removed.
3.  Select **Save changes**. A review page opens.
4.  Check the review, then choose one:
    -   **Publish version N** puts the changes in force for everyone who has the role. N is the next version number.
    -   **Save draft** keeps the changes as a draft. The role shows **Unpublished changes**, and its users keep the published version.

To change the name or description, select **Edit details** in the **⋯ More actions** menu. The change is saved to the draft and takes effect when you publish.

The review page shows:

-   **What changes**: the permissions being added and removed, and any prerequisites that come with them.
-   **Who this reaches**: where the role is assigned, how many users have it, and what they gain and lose.
-   **Resulting permissions**: the full list the role grants after you publish.
-   The version that is live now and the version that publishing makes.

People who are signed in may need to refresh the app before they see a published change.

### Drafts

-   **Publish a saved draft**: open the role, select **Save changes**, check the review, and select **Publish version N**.
-   **Discard a draft**: select **Cancel** on the role's page, then confirm. Users keep the published version. If the role was never published, it stays as an empty draft and keeps its API name.
-   **One draft at a time.** A role has one open draft. If another admin changes the role while you review it, the review page warns you that it is out of date. Go back and review the latest draft before you publish.
-   **Publish needs its own check.** The person who publishes must hold every permission in the draft. The person who saved the draft may hold different permissions.

## History

Select **History** in the role's ⋯ menu to see every change to a custom role, newest first. Each entry shows who made the change, when, and which permissions were added or removed. The entries come from the [audit log](/builder/v2/administration/audit-log). History is never removed. System admins can open History.

## Assign a custom role

After you publish a role, it appears in the role pickers for its scope:

-   **Workspace role**: in **Settings → User Management**, select **Invite**, or **Edit role** on a person's row. See [User management](/builder/v2/administration/user-management).
-   **Group role**: on the group's **Permissions** tab. See [Groups and Teams](/builder/v2/groups).
-   **AI Employee role**: on the AI Employee's **Permissions** tab. See [AI Employees](/builder/v2/core-concepts/ai-employees#roles-and-access).

Draft and disabled roles don't appear in the pickers. You can only assign a role whose permissions you hold yourself.

## Disable and enable a role

Select **Disable** in the role's **⋯ More actions** menu, then confirm. The role stops being given to anyone new, and it leaves every role picker. People who already have it keep it, with every permission it grants. You can still edit a disabled role. To take access away, edit the role, remove people from it, or delete it.

Select **Enable** to let the role be assigned again. A role that was never published can't be disabled.

## Delete a role

Select **Delete** in the role's ⋯ menu. The role stops granting anything at once, and you can't undo this. Its open draft is deleted too. Its history stays for the audit record.

-   **Workspace and group roles**: if people still have the role, choose another role in the same scope to move them to. The dialog shows what they gain and what they lose. Then you can delete it.
-   **AI Employee roles**: always choose a published AI Employee role to move assignments to, even if nobody has the role. While Ema moves the assignments, the role shows **Deletion pending**. People keep their access until the move completes.

The deleted role's API name stays reserved. Its name can be used again.

## Built-in roles

You can't change a built-in role's permissions. Its page shows what it grants. Its **⋯ More actions** menu offers **Clone**, and on workspace roles, **Turn off here**. In the roles list, the ⋯ menu of a built-in workspace role also offers **Users**, which opens the member list filtered to that role.

### Clone a built-in role

To change what a built-in role grants, clone it and change the clone. Select **Clone**, then follow the steps in [Create a custom role](#create-a-custom-role).

A clone of a built-in role remembers where it came from. When Ema changes the original, your role shows **Ema changed the role this was copied from**. Open your role to review the change:

-   **Adopt selected** adds the permissions you choose to a draft. Publish it to apply them.
-   **Dismiss** records that you reviewed the change and don't want it.
-   **Stop tracking** stops Ema from comparing your role with the original.

### Turn off a built-in role in your workspace

Select **Turn off here** to stop a built-in workspace role from being given to anyone new in your workspace. People who already have it keep it. Select **Turn back on here** to undo this. This change applies only to your workspace. You can't turn off System admin.

Your workspace may give a built-in role automatically, for example to invited people or to new people who sign in through SSO. To turn off that role:

-   Choose the custom role that new people get instead. It must be a published workspace role with more than workspace membership. If you have none, create and publish one first.
-   You need the `sso.manage_config` permission. See [Tenant management and SSO](/builder/v2/administration/tenant-and-sso#sso).

The replacement shows a **Replaces** marker in the roles list.

## Export and import a role

To move a custom role to another workspace or environment:

1.  In the role's ⋯ menu, select **Export**. This downloads the published name, description and permissions as a JSON file. While a draft is open, **Export draft** downloads the draft instead.
2.  In the other workspace, on the Roles tab, select **Import role**.
3.  Choose the JSON file (up to 1 MB). Enter a **Name** (the API name) and a **Display name** that are unique in that workspace.
4.  Select **Create draft**. Open the new role, check its permissions, and publish it.

You can also choose **Import role** as the starting point when you [create a role](#create-a-custom-role). Then you review the file's permissions in the create steps before you publish or save a draft.

An import never overwrites a role. If the file asks for a permission you don't hold, or one the workspace doesn't offer, the import is refused.

## API reference

The roles API is part of the auth service. Your workspace comes from your sign-in token.

Action

Route

Permission

List roles in a scope

`GET /roles?scope=workspace|group|ai_employee`

`role.view`

List the permissions a scope offers

`GET /capabilities?scope=…`

`role.view`

List a role's permissions

`GET /roles/{id}/capabilities`

`role.view`

List the people who have a role

`GET /roles/{id}/users`

`role.view`

Create a role (as a draft)

`POST /roles`

`role.create`

Clone a published role (as a draft)

`POST /roles/copy-scoped`

`role.create`

Import a role (as a draft)

`POST /roles/import`

`role.create`

Save a draft

`PUT /roles/{id}`

`role.edit`

Read or discard the open draft

`GET` or `DELETE /roles/{id}/draft`

`role.view` to read, `role.edit` to discard

Publish

`POST /roles/{id}/publish`

`role.edit`

Disable or enable

`POST /roles/{id}/disable`, `POST /roles/{id}/enable`

`role.edit`

List published versions

`GET /roles/{id}/versions`

`role.view`

Restore an earlier version (as a draft)

`POST /roles/{id}/revert`

`role.edit`

Export

`GET /roles/{id}/export`

`role.view`

Delete

`DELETE /roles/{id}?fallback_role_id=…`

`role.delete`

A new, cloned or imported role starts as a draft. Call publish to put it in force. Writes that change a draft, publish it or discard it send `expected_draft_revision`. If another admin changed the draft first, the call returns `409` and changes nothing. Read the draft again, then retry.

Every change to a role is recorded in the [audit log](/builder/v2/administration/audit-log), with the permissions that moved.

## What's next

-   [Governance and permissions](/builder/v2/administration/governance-and-permissions): the built-in roles and the full permissions reference.
-   [User management](/builder/v2/administration/user-management): give people a workspace role.
-   [Groups and Teams](/builder/v2/groups): assign group roles.
-   [Audit log](/builder/v2/administration/audit-log): see who changed a role and when.
