---
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, Models, Bindings, 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 permissions (e.g., "3/4").

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:

### Data Collection

| Category | Typical Permissions |
|----------|-------------------|
| **Devices** | Add, change, delete, view |
| **Tags** | Add, change, delete, view |
| **Device Sets** | Add, change, delete, view |
| **Protocols** | Change, view |

### AI & Automation

| Category | Typical Permissions |
|----------|-------------------|
| **AI Models** | Add, change, delete, view |
| **Scan Groups** | Add, change, delete, view |
| **Component Libraries** | Add, change, delete, view |
| **Component Environments** | Add, change, delete, view |

### Visualization

| Category | Typical Permissions |
|----------|-------------------|
| **Trends** | Add, change, delete, view |
| **Dashboards** | Add, change, delete, view |

### System

| Category | Typical Permissions |
|----------|-------------------|
| **System Administration** | Manage users, roles, services |
| **System Settings** | View and change system settings |
| **Events** | View event log |

### API Access

| Category | Typical Permissions |
|----------|-------------------|
| **API Clients** | Add, change, delete, view |

Each permission controls a specific action. For example, a user with "Can change device" can edit device settings, but cannot delete devices unless they also have "Can delete 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 — e.g., "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