How Users, Groups & Permissions Work

How users, groups, permissions, and customer and device access work together — with every permission, device action, and user field for lookup.

In octoja, groups control all access. A group decides three things: which features its members can use (permissions), which customers they can reach (customer access), and which of those customers' devices they can reach and what they may do there (device access). There are no fixed roles — you build your access model from groups that match how your team works.

Users

A user is a person who signs in to octoja — with a password, optionally with two-factor authentication, or through SSO (see How sign-in works). Users hold no permissions of their own; they get everything through their groups. A user with no group membership can sign in and view their own profile, but reaches nothing else in octoja.

You manage users under Administration → Users with the User Management permission. A user account consists of these fields:

Field	Type	Required	Default	Description
Email	Email	Yes	—	Unique email address, also used as the login name.
First Name	Text	No	—	User first name.
Last Name	Text	Yes	—	User last name.
Mobile Number	Text	No	—	Number used for SMS and calls. App push targets registered app devices and does not require a mobile number; see Mobile notifications. Preferably in international format with country code. Users can set their own under My Profile.
Remote Support Display Name	Text	No	Technician name template, otherwise the user's name	Shown on the customer's device during remote support in place of the user's name. Set by an administrator on the user detail page.
Password	Text	No	Not set	Optional password, at least 8 characters. Without a password, the user can only sign in via linked logins; an administrator can set one later.
Groups	Multi-select	No	None	Group memberships that grant permissions. Set in the Invite User dialog, or on the group under Administration → Groups.
Two-Factor Authentication	Setup dialog	No	Disabled	Time-based one-time password (TOTP) second factor. Set up by scanning a QR code — from the user's own profile, or by an administrator on the user detail page.
Linked Logins	List	No	None	External identity-provider links (e.g. Microsoft Entra ID, Google) bound to this user.

The user detail page holds Mobile Number, Remote Support Display Name, Password, Two-Factor Authentication, and Linked Logins. Group membership is not edited there but on the group. For API access, see Users API.

Groups

A group bundles permissions with a customer access and a device access scope. A user can belong to several groups; their effective access is the union of all their groups. If Group A grants Case Management and Group B grants Monitoring Check Management, for example, the user gets both. No group can take away access that another group grants.

You manage groups under Administration → Groups with the Group Management permission. The group editor has four tabs:

Tab	Contents
General	Name, the Administrator group toggle, and the group's Members.
Permissions	The access level for each feature.
Customer Access	Which customers members reach.
Device Access	Which devices members reach and which actions they may perform there.

A newly created group grants nothing: no permissions, no customers, no devices. Membership is edited on the group; the user list under Administration → Users shows each user's groups.

Administrator groups

A group can be marked as an Administrator group. Its on-screen description reads: "New permissions introduced in future updates are granted to administrator groups automatically." Enable it on your full-access group so it never falls behind when an octoja update adds a new permission.

The flag also unlocks instance-wide areas that no permission covers. Only members of an administrator group can reach — regardless of their other permissions:

Administration → Audit Log (see The audit log)
under Administration → Settings, the pages Agent enrollment policy, Authentication, Active alarms, Beta features, Custom Domain, Email sender, and Remote support

Manually resolving alarms on Active alarms requires membership in an administrator group plus Manage Alert Configurations.

Group Management protection

octoja ensures that at least one user always keeps the Group Management permission (groups.manage). You may remove it from yourself as long as someone else still has it; a change that would leave no user with it — by editing or deleting a group, emptying its members, or deleting a user — is blocked. Other permissions, including User Management, are not protected. Be careful when removing them from your own groups.

Permissions

Permissions decide which features a group's members can use. The Permissions tab arranges them in six areas, and every row carries a selector rather than a checkbox:

Six rows are graduated — Customers, Cases, Patch Management, Reports, TV View, and Automations. They offer No access, Read, or Read & write. Read & write always grants the read permission as well.
Every other row offers No access or Enabled.
Indented rows (marked ↳ in the tables) extend the row above and can only be set once that row has at least Read or Enabled.

The Admin group's Permissions tab with access-level selectors grouped by feature area and the Save button.

The tables list the permission each level grants. The identifier appears in technical contexts such as the API.

Customers & Cases

Row and level	Permission	What it allows
Customers — Read	View Customers `customers.view`	View customers.
Customers — Read & write	Customer Management `customers.manage`	Create, edit, and delete customers and their sites.
Cases — Read	View Cases `tickets.view`	View cases.
Cases — Read & write	Case Management `tickets.manage`	Create, edit, comment on, close, and delete cases.

Monitoring & Alerts

Row	Permission	What it allows
Monitoring Check Management	`monitoring-checks.manage`	Manage config packages and assign monitoring checks or software deployments to devices. Without it, Configuration → Config Packages is not accessible.
↳ Custom Check Management	`custom-checks.manage`	Manage the instance-wide custom check catalog.
Check Repository Management	`check-repositories.manage`	Manage check repositories, the instance-wide sources of checks.
Manage Alert Configurations	`alert-configs.manage`	Create, edit, and delete alert configurations for monitoring checks.

Patch & Software

Row and level	Permission	What it allows
Patch Management — Read	View Patch Policies and Cycles `patch-management.read`	View patch policies, cycles, and results.
Patch Management — Read & write	Patch Policy Management `patch-management.write`	Create, edit, and delete patch policies and manage blocked updates.
↳ Manage Patch Cycles	`patch-cycles.approve`	Approve, reject, or defer updates and clear user decisions in upcoming patch cycles, and refresh or cancel those cycles.
↳ Emergency Patch Cycles	`patch-cycles.emergency`	Create emergency patch cycles that bypass ring ordering.
Custom Package Management	`custom-packages.manage`	Create, upload, and publish custom software packages.

Reporting

Row and level	Permission	What it allows
Reports — Read	View Reports `reports.view`	View and generate reports.
Reports — Read & write	Manage Report Templates and Schedules `reports.manage`	Manage report templates and schedules.
TV View — Read	TV View `tv-view.view`	View the TV dashboard.
TV View — Read & write	Manage TV View `tv-view.manage`	Manage TV view settings, including alert sounds.

Administration

Warning: User Management and Group Management apply to the entire octoja instance; customer and device access do not restrict them. With Group Management, members can grant any permissions and access, mark groups as administrator groups, and change memberships — including expanding their own access. User Management allows changes to other users' accounts, including passwords, two-factor authentication, and linked logins. Grant both permissions only to trusted instance administrators.

Row and level	Permission	What it allows
User Management	`users.manage`	Create, edit, and delete user accounts.
Group Management	`groups.manage`	Create, edit, and delete groups, set their members, and open Access Overview.
Custom Field Management	`custom-fields.manage`	Define and manage custom fields for customers and devices.
Agent Management	`agents.manage`	Manage agent enrollment settings and enrollment tokens.
Integration Management	`integrations.manage`	Configure and manage third-party integrations such as Lywand, webhooks, and Teams.
MCP Usage	`mcp.use`	Connect and use MCP clients (see MCP: overview and access).
Branding Management	`branding.manage`	Customize the instance's white-labeling.
Automations — Read	View Automations `automations.view`	View saved workflows and runs, run them, and cancel them. Manual runs also require the Run Script device action on the target device.
Automations — Read & write	Manage Automations `automations.manage`	Create, edit, and delete workflows and test unsaved steps.

Row	Permission	What it allows
Tag Rules	`tags.manage`	Manage tag rules that automatically apply tags to devices.
Create Custom Tags	`tags.create-custom`	Create new custom tags. Users without this permission can only apply existing tags.

Customer access

Customer access decides which customers a group's members can see and work with. What they may do there is set by the permissions.

Option	Meaning
Access to all customers	Every customer in the organization, including customers added later.
Access to selected customers	An explicitly selected list of customers, regardless of the rules.
Access by rules	Additionally every customer that matches the rules — by its customer tags (including partial matches with matches text and does not match text) or by a customer custom field. New matching customers are included automatically.

Selected customers and rules can be combined in the same group. Rules only grant access; a rule that excludes customers does not stop another group from granting them.

Device access

Device access refines what members reach within their accessible customers. A group with no customer access reaches no devices, whatever its device access says.

Option	Meaning
Access to all devices	Every device of the accessible customers. If the group has Access to all customers, this also includes devices without an assigned customer.
Access by rules	Only devices that match the rules. Without conditions, the group grants no device access.

Allowed actions decide what members may do on the devices they reach. A group that reaches devices but has no allowed actions gives read-only device access: members can see the devices but cannot act on them.

Action	What it allows
Service Control	Start, stop, and restart Windows services.
Process Control	View and terminate running processes.
Remote Desktop	Start an interactive remote desktop session.
Terminal	Open a remote terminal or shell.
Registry	Browse and edit the Windows registry.
File Browser	Browse, download, and upload files on the device.
Software Management	Install, update, and remove software.
Event Log	View and export the device event logs.
Run Script	Execute scripts on the device.
Run Maintenance	Trigger maintenance tasks on the device.
Edit Device	Edit device name, alias, and tags.
Delete Device	Remove the device from the organization.
Send Notification	Show a message on the signed-in user's screen.
Bypass Remote-Desktop Consent	Connect even when the user declines consent on a consent-required device.
Active Directory	View, disable, and delete Active Directory users on domain controllers.
VMware management	Power virtual machines on and off on ESXi and vCenter hosts.
Wake Device	Send Wake-on-LAN packets through an online peer agent at the same customer location.
Local user management	Create local user accounts and enable, disable or change the password of an existing one.
Maintenance mode	Put a device into maintenance mode to pause its checks, automations, and alerts.
Hyper-V management	Manage Hyper-V VM power states and checkpoints. Reading VM details also requires Run Maintenance. The feature must be enabled for the instance separately from this action; the linked guide explains enablement.
Proxmox VE management	Start, stop and snapshot virtual machines and containers on Proxmox VE hosts.

How restricted customer access affects configuration packages, automations and patch policies that span several customers is described under Shared configurations.

Access Overview

The Administration → Access Overview page shows the combined result of every group — who can reach which customers and devices, and why. It requires the Group Management permission and offers three views: By user, By customer, and By device. For each entry you see the customers and devices in reach, the Allowed actions column (with an All badge when every action is allowed), and the reason: which group grants the access and whether it applies to all customers, to all devices, through an explicit assignment, or through a rule.

Example groups

These examples are for orientation only — you can combine permissions and access in any way.

Group	Permissions	Customer and device access
Administrators	All, with the Administrator group toggle on	Access to all customers, Access to all devices, all actions
Technicians	Customer Management, Case Management, Monitoring Check Management, Manage Alert Configurations, Patch Policy Management, Manage Patch Cycles	All customers and devices with operational actions such as Remote Desktop, Terminal, File Browser, and Software Management
Help Desk (one customer)	View Customers, Case Management	One selected customer, its devices read-only (no allowed actions)
Read Only	View Cases, View Patch Policies and Cycles	As needed, no allowed actions

Was this helpful?

Still need help? Ask the team