Roles & Permissions
A role is a named set of capabilities. You give people, groups and service accounts one or more roles, and each assignment applies at a scope: the whole organisation, one fleet, one device, or one configuration. Admiral has seven built-in roles. You can also build custom roles from the same capability list.
Scopes
| Scope | What it covers |
|---|---|
| Organisation | Every fleet, device and configuration in the organisation |
| Fleet | One fleet and the devices in it |
| Device | One device |
| Configuration | One configuration and its versions |
A grant cascades from organisation to fleet to device. A role assigned to a fleet applies to that fleet and its devices, not to other fleets. A configuration-scope grant applies to that configuration only. An organisation-scope grant applies to every configuration.
Each capability lists the scopes where it can be granted. A capability that does not apply at the scope you choose is skipped (see Assigning roles).
Several roles at once
A person, group or service account can hold several roles at different scopes. Assignments are additive: the holder gets the union of what their assignments grant at each scope.
Examples:
- Engineer for the organisation, plus Remote access on one fleet. The person can deploy, configure and manage devices in every fleet. Root shell works only in the fleet where Remote access is assigned. Engineer on its own does not include root shell.
- Technician on one fleet. The person can operate, provision and recover devices, change network settings, and control device screens in that fleet. They have no access to other fleets.
- Viewer on one configuration. The person can see that configuration. Viewer's other capabilities (devices, screens, telemetry, AirDetect) are not granted at configuration scope, so the grant covers only View configurations.
Capability reference
Capabilities are grouped by area. Scopes shows where a capability can be granted: O is organisation, F is fleet, D is device, C is configuration. Includes lists the capabilities a grant also gives. The capability ID is shown for the API and CLI; the dashboard shows the label.
Devices
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| View fleets and devices | devices.view | Read device and fleet status, workload state, services, volumes, specs, events, fleet settings and policies, and search results | O F D | |
| Edit fleets and devices | devices.edit | Rename devices, change tags and descriptions, edit fleet settings and custom metrics | O F D | View fleets and devices |
| Add devices | devices.provision | Claim and pair devices into a fleet, manage provisioning profiles and installer downloads for that fleet, move devices into the fleet | O F | View fleets and devices |
| Remove devices | devices.delete | Delete, unclaim, factory reset or wipe devices, delete a fleet, move devices out of a fleet | O F D | View fleets and devices |
| Create fleets | fleets.create | Create fleets | O | |
| Operate devices | devices.operate | Reboot and shut down devices, run batch power actions, start, stop, restart and recreate workloads, start and stop system services, re-push configuration, pin, pull and delete images | O F D | View fleets and devices |
| Update device OS | devices.update | Push OS updates to a device or batch, set the fleet OS version policy and update window | O F D | View fleets and devices |
| Manage volumes | volumes.manage | Create and delete volumes and volume backups | O F D | View fleets and devices |
| Recover devices | devices.recover | Reveal a device recovery key and grant remote unlock. Dashboard session only | O F D | View fleets and devices |
Workload and remote
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| Open workload terminal | remote.exec | Open a terminal in a workload from the dashboard, and run commands in a workload with the admrl CLI | O F D | View fleets and devices |
| Root shell (SSH) | remote.shell | Open a root shell on the device over SSH, use debug mode, and trust SSH keys | O F D | Open workload terminal, Control device screen |
| Manage SSH access | remote.manage | Turn fleet SSH access on or off | O F | View fleets and devices |
Deploy
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| View configurations | configs.view | View configurations, their versions and images, and registry credential names | O C | |
| Create configurations | configs.create | Create configurations | O | View configurations |
| Edit configurations | configs.edit | Edit configurations, add versions, manage images | O C | View configurations |
| Delete configurations | configs.delete | Delete configurations | O C | Edit configurations |
| Assign configurations | deploy.assign | Assign configurations to a fleet or device, edit fleet and device documents, adopt or discard local overrides | O F D | View fleets and devices |
| Run rollouts | rollouts.manage | Create, pause, resume, cancel, roll back, delete and stop rollouts. Creating a rollout also requires Assign configurations on every target fleet | O | View configurations |
| Edit secret files | secrets.edit | Manage secret files on an organisation, fleet, device or configuration | O F D C | |
| Edit registry credentials | registry.edit | Create, edit and delete registry credentials | O | View configurations |
Network and policy
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| Edit network settings | network.edit | Edit device and fleet network configuration | O F D | View fleets and devices |
| Edit device policy | policy.device | Edit operational device policy at organisation, fleet or device level | O F D | View fleets and devices |
| Edit security policy | policy.security | Edit fleet security requirements, USB policy, and image signature policy | O F D | View fleets and devices |
Observe
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| View telemetry and logs | telemetry.view | View metrics, historical logs, the live log tail, and telemetry queries | O F D | View fleets and devices |
| Edit alert rules | alerts.edit | Create, edit and delete alert rules | O | View telemetry and logs |
| Run diagnostics | diagnostics.run | Run the diagnostics probe, memory tests, and diagnostic bundles, and view system services | O F D | View fleets and devices |
| View AirDetect | airdetect.view | View AirDetect presence analytics | O F D | View fleets and devices |
| Export AirDetect data | airdetect.export | Export raw AirDetect session data as CSV | O F | View AirDetect |
Screen
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| View device screen | screen.view | View device screenshots and the screen preview | O F D | View fleets and devices |
| Control device screen | screen.control | Control the device's on-device console. Dashboard session only | O F D | View device screen |
Organisation
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| Manage members and groups | members.manage | Invite and remove members, manage groups and group membership | O | |
| View access | access.view | See other people's assignments, use the access explorer for other subjects, and see service accounts and key metadata | O | |
| Manage access | access.manage | Create, edit and delete roles, make assignments, manage service accounts and IAM policies, the fleet Access tab, and member organisation roles | O F | View access |
| Manage organisation settings | org.settings | Change organisation settings, manage webhooks and notification channels, and read webhook signing secrets | O | |
| View audit log | org.audit | View the audit log and the support access trail | O | |
| Manage support access | org.support_access | Turn Admiral support access on and off | O |
Billing
| Capability | ID | What it allows | Scopes | Includes |
|---|---|---|---|---|
| View billing | billing.view | View the billing overview, usage, invoices, and registry fallback usage | O | |
| Manage billing | billing.manage | Change the plan and add-ons, and manage payment methods and billing details | O | View billing |
| Turn on billed fleet services | services.manage | Turn AirDetect and Registry fallback on or off for a fleet. The organisation must have the add-on | O F | View fleets and devices |
Owner-only actions are not capabilities. Only an Owner can delete the organisation, create nested organisations, and assign or remove the Owner role.
Built-in roles
| Role | Assignable at | What it contains |
|---|---|---|
| Owner | Organisation only, by an Owner | Everything, plus the owner-only actions |
| Administrator | Organisation, fleet, device | Every capability valid at the scope it is assigned to. At organisation scope this includes organisation management and billing. At fleet or device scope, organisation-only capabilities are skipped |
| Engineer | Organisation, fleet, device | Deploy, configure and manage devices, and view telemetry, without root shell. Includes View fleets and devices, Edit fleets and devices, Add devices, Operate devices, Update device OS, Manage volumes, View, Create and Edit configurations, Assign configurations, Run rollouts, Edit secret files, Edit registry credentials, Edit network settings, Edit device policy, Edit security policy, View telemetry and logs, Edit alert rules, Run diagnostics, View AirDetect, Export AirDetect data, View device screen, Create fleets, View billing |
| Technician | Organisation, fleet, device | Day-to-day operations and recovery. Includes View fleets and devices, Operate devices, Add devices, Edit network settings, Run diagnostics, View device screen, Control device screen, Recover devices, View telemetry and logs, View AirDetect, View configurations |
| Viewer | Organisation, fleet, device | Read-only. Includes View fleets and devices, View device screen, View telemetry and logs, View AirDetect, View configurations |
| Billing manager | Organisation only | View billing, Manage billing |
| Remote access | Organisation, fleet, device | Root shell (SSH). Add it to another role to allow root shell and terminal access. Includes Open workload terminal and Control device screen |
Owner and Administrator are the only built-in roles that include Manage access, Manage members and groups, and Manage organisation settings. Those capabilities are organisation-scope, so Administrator assigned to a fleet does not hold them. Manage billing is included only in Billing manager, Administrator and Owner.
Custom roles
Create a custom role from Access > Roles with New role. Under Start from, choose a built-in or existing role, or start from scratch. Select capabilities; capabilities listed under Includes are switched on with them.
- Capabilities & Risk shows the capabilities in the role and their risk levels before you save.
- Compare with shows the differences from another role.
- Duplicate role copies a role. The copy is a new role; changing it does not change the original.
Changing a role changes the access of everyone who holds it.
Assigning roles
You assign roles to users, groups and service accounts. Each assignment has a role and a scope: the organisation, a fleet, a device, or a configuration. Assignments are saved even if some capabilities cannot apply at the chosen scope. The response lists each skipped capability with one of these reasons:
organisation_only: the capability only works at organisation scope.cannot_delegate: you do not hold the capability at that scope.cross_tenant: the target is in another organisation.not_grantable: the capability cannot be granted at that scope.
You can only grant capabilities you hold at the target scope. Organisation-wide Manage access can assign roles anywhere in the organisation. Fleet-level Manage access can assign roles inside that fleet only. Only an Owner can assign the Owner role.
What changes for existing organisations
When an organisation moves to roles, members become Engineer at organisation scope. Owners and administrators keep their access as Owner and Administrator. Fleet-level roles map to Administrator, Engineer or Viewer at fleet scope.
Compared with a member today, an Engineer:
- Gains: Run rollouts includes deleting rollouts. Members could not delete rollouts before.
- Loses: Manage SSH access, the fleet switch for SSH. Members could change it because they were fleet editors.
- Loses: Manage access at fleet scope, which includes the fleet Access tab.
- Loses: Managing webhooks, which now needs Manage organisation settings.
- Loses: The AirDetect and Registry fallback switches. Members could not use these before, because they were already limited to admins. They are now controlled by Turn on billed fleet services.
- Loses: The audit log and the support access switch. Members could not use these before either: both were already limited to organisation admins.
Personal tokens, CLI sign-ins and sessions
A personal API token or CLI sign-in acts with the roles of the user who created it. You cannot narrow a token to a subset of those roles. To limit what an automation or assistant can do, use a service account, or a dedicated user with a narrow role.
Tokens cannot manage roles, members or access. A token can read its own capabilities.
These actions need a signed-in dashboard session. Personal API tokens, CLI sign-ins and MCP tokens are refused:
- Reveal a device recovery key (Recover devices)
- Grant remote unlock (Recover devices)
- Control the device screen (Control device screen)
Starting an offline memory test, which reboots the device into a one-shot test boot, also needs a signed-in dashboard session. API tokens, CLI tokens and service accounts receive 403 with operator_required.