Roles & Permissions

Navigate to System > Roles to manage access control. The page lists every role in a table — Role Name, Users, and Permissions — with two summary cards above it. Click a role row to open its detail page.

Access Levels

Every user falls into one of three access levels:

Level	Description
Superuser	Full access to everything. Bypasses all permission checks. Superusers do not need a role assignment — any roles they hold add nothing.
Role	A named set of permissions. Koios ships three built-in roles and you can create your own. A user can hold any number of roles and receives the combined permissions of all of them.
View Only	Default level for users who hold no role and have no permissions granted to them directly. Read-only access: can view data but cannot make changes.

Built-in Roles

Koios creates three roles on first boot. They appear in the role table alongside any you create, and you can rename, duplicate, or delete them like any other role.

Role	What it can do
Operator	Day-to-day operation: create and manage trends and dashboards, enable and disable devices, tags, models, scan groups, device sets, and component environments, acknowledge events, start and stop services, and edit the hardware alarm, history, and advanced metrics settings.
Engineer	Everything Operator can do, plus creating, editing, and deleting devices, tags, models, scan groups, device sets, component libraries, and component environments, managing protocols, component stacks, OPC-UA certificates, and API clients, and editing the licensing settings.
Administrator	Everything Engineer can do, plus managing users and roles, managing licenses and system logs, managing web interface certificates, viewing and exporting the audit trail, and editing the retention, history retention, and backup settings.

None of the three is a superuser. An Administrator works through the permission system like every other role, so a permission nobody has toggled on is a permission nobody holds.

Renaming a built-in role costs it future permissions

Upgrades grant new permissions to the built-in roles by name. If you rename Operator, Engineer, or Administrator, the upgrade skips it and prints a warning naming the permission instead — you then grant it by hand on the Permissions tab. Duplicate the role and rename the copy if you want a differently named variant.

Superusers and View Only

Two summary cards sit above the role table. Neither is a role, so neither can be edited or deleted:

Superusers: the number of users with superuser privileges. Superuser status is set at the account level, not through role assignment. Click the card to open the Users list filtered to superusers.
View Only: the number of users who hold no role. This is the default access level. Click the card to open the Users list filtered to those accounts.

Creating a Role

Click Create Role
Enter a Role Name
Optionally select Base Permissions to copy permissions from an existing role
Click Create Role

The new role starts with no users. Add users and configure permissions from the role's detail page.

Role Detail

Click a role row to open its detail page, which has two tabs and a back link to the role list.

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. This role is added to whatever roles each user already holds; a note lists any selected users who are already in another role.
Remove users: click the remove button on a user row. The user loses this role but keeps any others. They drop to View Only only if this was their last one.

Users can hold several roles

A user can be assigned any number of roles and receives the combined permissions of all of them. Adding a role never removes one the user already has.

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 entity categories offer a Manage toggle and a Control toggle; some offer Manage only. The System categories instead list one toggle per capability.

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

The Audit Trail category holds three permissions governing the Audit Log: view it, export it, and purge expired records. Purge covers retention cleanup only — there is no permission to create, edit, or delete an individual record, because the trail is append-only for everyone, including administrators. Grant export only to roles that need to produce compliance evidence.

Managing Roles

Editing a Role

Open the role's menu (three-dot icon) in the detail header and select Rename 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 are assigned to it. Superusers and View Only are not roles and cannot be deleted.

Permission Categories

Permissions are grouped by domain and entity type. Most entity categories expose up to two permissions:

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

The System categories do not follow that pattern — they expose one toggle per capability, listed individually below.

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
Component Stacks	Manage

Visualization

Category	Permissions
Trends	Manage
Dashboards	Manage

System

Category	Permissions
System Administration	Manage users, manage roles, manage licenses, manage system logs, manage history retention
System Settings	Edit hardware alarm settings, edit history settings, edit retention settings, edit backup settings, edit advanced metrics, manage licensing, start/stop/restart services, manage HTTPS certificates (see Certificates)
OPC-UA Certificates	Manage OPC-UA client certificates, including downloading their private keys (see OPC-UA Certificates)
Events	Acknowledge events
Network Diagnostics	Scan the network
Audit Trail	View audit records, export audit records, purge expired audit records

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.

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

Start with the built-in roles — Operator, Engineer, and Administrator cover most teams as they ship
Create additional roles only where a team needs a scope the built-in three do not cover, using Base Permissions to copy the closest built-in role as a starting point
Configure permissions on each role using the toggle switches
Create user accounts and assign each user to the appropriate role
Adjust as needed: add or remove permissions from roles, and add or remove role assignments on each user

What's Next

Users: create accounts and assign roles

Users Audit Log