---
title: "Roles & Permissions"
description: "Create roles, assign permissions, and control what users can do"
source_url: https://ai-ops.com/docs/system/roles-permissions
---

# Roles & Permissions

Navigate to **System > Roles** to manage access control. The page uses a split layout: roles listed on the left, details on the right.

---

## Access Levels

Every user falls into one of three access levels:

| Level | Description |
|-------|-------------|
| **Superuser** | Full access to everything. Bypasses all permission checks. Cannot be assigned a role. |
| **Role** | Custom permissions defined by an administrator. A user can belong to one role at a time. |
| **View Only** | Default level for users not assigned to any role. Read-only access: can view data but cannot make changes. |

---

## Built-In Entries

Two entries always appear in the role list and cannot be deleted:

- **Superusers**: lists all users with superuser privileges. Superuser status is set at the account level, not through role assignment.
- **View Only**: lists all users who have no role assigned. This is the default access level.

---

## Creating a Role

1. Click **Create Role**
2. Enter a **Role Name**
3. Optionally select **Base Permissions** to copy permissions from an existing role
4. Click **Create Role**

The new role starts with no users. Add users and configure permissions from the role detail panel.

---

## Role Detail

Select a role from the list to view its details. The detail panel has two tabs.

### Users Tab

Shows all users assigned to this role. From here you can:

- **Add users**: click **Add User** and select from a multi-select dropdown. Users already in another role will be moved to this one (a warning is shown).
- **Remove users**: click the remove button on a user row. The user moves to View Only.

> [!NOTE] One role per user
> A user can only belong to one role at a time. Adding a user to a role automatically removes them from their previous role.

### Permissions Tab

Permissions are organized by category (Devices, Tags, AI Models, System, etc.). Each category is an expandable section showing toggle switches for individual permissions.

A badge on each category header shows the count of enabled toggles out of those available (e.g., "1/2"). Most categories offer a **Manage** toggle and a **Control** toggle; some offer **Manage** only.

Toggle the switches to grant or revoke permissions, then click **Save Changes**. All users in the role immediately receive the updated permissions.

---

## Managing Roles

### Editing a Role

Click the **edit** button in the role detail header to rename the role.

### Duplicating a Role

Open the role's menu (three-dot icon) and select **Duplicate Role**. A new role is created with the same permissions and a name like "Original Name (Copy)".

### Deleting a Role

Open the role's menu and select **Delete Role**. A confirmation dialog shows how many users will be moved to View Only. Built-in entries (Superusers, View Only) cannot be deleted.

---

## Permission Categories

Permissions are grouped by domain and entity type. Each entity exposes up to two permissions:

- **Manage**: full control, including create, edit, and delete.
- **Control**: operational actions only, such as enabling or disabling the entity.

### Data Collection

| Category | Permissions |
|----------|-------------|
| **Devices** | Manage, Control |
| **Tags** | Manage, Control |
| **Device Sets** | Manage, Control |
| **Protocols** | Manage |

### AI & Automation

| Category | Permissions |
|----------|-------------|
| **AI Models** | Manage, Control |
| **Scan Groups** | Manage, Control |
| **Component Libraries** | Manage |
| **Component Environments** | Manage, Control |

### Visualization

| Category | Permissions |
|----------|-------------|
| **Trends** | Manage |
| **Dashboards** | Manage |

### System

| Category | Permissions |
|----------|-------------|
| **System Administration** | Manage users, roles, licenses, logs, retention |
| **System Settings** | Change system settings |
| **Events** | Acknowledge events |

### API Access

| Category | Permissions |
|----------|-------------|
| **API Clients** | Manage |

Each permission controls a scope of actions. For example, a user with **Control Device** can enable or disable devices, but cannot create, edit, or delete them without **Manage Device**.

> [!TIP] Start with a template
> When creating a new role, select an existing role's permissions as the base, then adjust individual toggles. This is faster than enabling permissions one by one.

---

## Typical Workflow

1. **Create roles** for your team, for example "Operator" (view + limited control), "Engineer" (full device/tag/model access), "Admin" (everything)
2. **Configure permissions** on each role using the toggle switches
3. **Create user accounts** and assign each user to the appropriate role
4. **Adjust as needed**: add or remove permissions from roles, move users between roles

---

## What's Next

- [Users](https://ai-ops.com/docs/system/users.md): create accounts and assign roles