> For the complete documentation index, see [llms.txt](https://mercure-technologies.gitbook.io/xprem/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mercure-technologies.gitbook.io/xprem/security/user-roles-and-rbac.md).

# User roles & RBAC

{% hint style="warning" %}
User roles are an Enterprise feature. Creating roles and granting them to users requires an active Enterprise license (see [open-core-and-licensing](/xprem/references/open-core-and-licensing.md)).
{% endhint %}

Out of the box the dashboard knows two kinds of accounts: administrators who can do everything, and [members](/xprem/dashboard/users.md) who can only read. User roles refine that split. You decide which apps each member can see, and what they are allowed to do on each of them, by assigning reusable roles and, when needed, individual permissions.

### How access works

An account is either an **administrator** or a **member**. Administrators bypass roles entirely: they see every app and can perform every action, exactly as without this feature. For members, access is granted app by app. A member only sees the apps you granted them; every other app is filtered out of their dashboard and answered with a not-found by the API, as if it did not exist. A member with no grant at all sees an empty dashboard, and the **Users** page points them out with a **No app access** badge so you notice before they do.

What a member may do on a granted app comes from two sources that add up:

* a **role**, a named and reusable set of permissions such as "Release manager";
* optional **custom permissions**, granted directly on top of the role for one-off needs.

A grant that carries neither still matters: it gives read-only access to the app.

The server enforces all of this on every request, with the same freshness rule as the admin flag: revoking a grant or demoting an account takes effect immediately, not when the session token expires.

### Roles

A role is a permission set you define once and assign to as many users as you want. You manage them from **Roles** in the **Access & Security** section of the sidebar: give the role a name, toggle the permissions it carries, and save. Roles are global; whether one applies to a given app is decided per user, at assignment time.

A role that is still assigned to someone cannot be deleted. Unassign it everywhere first, so removing a role is always an explicit decision rather than a silent loss of access.

### Assigning access

{% stepper %}
{% step %}
**Create a role**

Open **Roles** and create the sets your team needs, for example a "Release manager" role carrying the two rollout permissions and the channel branch change.
{% endstep %}

{% step %}
**Grant it to a user**

Open **Users**, select **Roles** on the member's row, and grant them the apps they work on. For each app, pick a role; if a one-off permission is missing from the role, enable **Custom permissions for this app** and add it on top. The same panel carries the **Administrator** switch, so promoting someone and scoping someone down happen in the same place.
{% endstep %}

{% step %}
**Or do it at creation**

When you create a user, the same assignment section appears directly in the creation form, so a new member starts with the right access instead of an empty dashboard.
{% endstep %}
{% endstepper %}

### Permissions reference

| Permission               | What it allows                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `app:rename`             | Change the display name of the app.                                                    |
| `app:delete`             | Delete the app with all of its branches, channels and updates.                         |
| `certificate:read`       | Download the app's signing certificate.                                                |
| `branch:create`          | Create update branches.                                                                |
| `branch:delete`          | Delete branches.                                                                       |
| `channel:create`         | Create release channels.                                                               |
| `channel:delete`         | Delete release channels.                                                               |
| `channel:edit-branch`    | Change which branch a release channel serves.                                          |
| `channel-rollout:manage` | Start a progressive channel rollout, adjust its percentage, promote or revert it.      |
| `update-rollout:manage`  | Set or revert the rollout percentage of a single update.                               |
| `apikeys:manage`         | Create and revoke API tokens and edit their [access](/xprem/security/token-access.md). |
| `identity:manage`        | Allow user to manage custom devices attributes                                         |
| `identity:read`          | Allow user to retrieve devices                                                         |
| `observe:read`           | Allow user to access metrics/logs                                                      |

Creating apps, managing users and roles, the Enterprise license and the [SSO configuration](/xprem/security/single-sign-on-sso.md) remain administrator-only: they are server-wide powers rather than per-app ones.

### When the license expires

Without an active Enterprise license the dashboard falls back to the standard model: members are read-only again and see every app, administrators keep full access, and nothing is enforced from the grants. The roles and grants themselves are not deleted; they stay stored, dormant, and start applying again the moment a license is activated. An expired license never widens what a member could do, it only widens what they can see.

### See also

[Token access](/xprem/security/token-access.md) scopes what each API token may do, on which branches, and from which networks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mercure-technologies.gitbook.io/xprem/security/user-roles-and-rbac.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.