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.
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. 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.manageandgroup.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
- On the Roles tab, select Create role.
- Choose the Role scope: Workspace, Group or AI Employee.
- Enter a Name and a Description. The description helps people choose the right role when they assign it.
- 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.
- Select Continue.
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. 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.
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, androle.create,role.editandrole.deleteneedrole.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.
- On the role's page, select Edit.
- Change the permissions. The footer counts the permissions you added and removed.
- Select Save changes. A review page opens.
- 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. 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.
- Group role: on the group's Permissions tab. See Groups and Teams.
- AI Employee role: on the AI Employee's Permissions tab. See AI Employees.
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.
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_configpermission. See Tenant management and 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:
- 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.
- In the other workspace, on the Roles tab, select Import role.
- Choose the JSON file (up to 1 MB). Enter a Name (the API name) and a Display name that are unique in that workspace.
- 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. 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, with the permissions that moved.
What's next
- Governance and permissions: the built-in roles and the full permissions reference.
- User management: give people a workspace role.
- Groups and Teams: assign group roles.
- Audit log: see who changed a role and when.