How to manage roles and custom roles
Every user carries one role. The role decides what they are allowed to do.
Requirements
- System roles: all plans. Assigning them needs Owner.
- Custom roles: Cosmos. Managing them needs Owner.
The five system roles
| Role | Intended for | Broadly can |
|---|---|---|
| Owner | The account holder | Everything, including users, organization settings, and billing |
| Admin | Operational administrator | Full asset, category, and maintenance management; read users; no user management |
| Manager | Team or site lead | Create and update assets, assign, manage maintenance, view reports; no deletion, no user management |
| Employee | Someone who does the work | Read and update assets, complete maintenance, check items out and in |
| Viewer | Read-only stakeholder | Read assets, categories, departments, and checkouts |
Full breakdown: Roles and permissions.
Assigning a role
Roles are assigned at Dashboard → Users, by an Owner. See Changing user roles.
Roles are not plan capabilities
Two independent checks run, and both must pass:
| Question | Decided by | |
|---|---|---|
| Permission | Is this person allowed to? | Their role |
| Capability | Is this organization's plan allowed to? | The plan |
A Viewer on Cosmos still cannot delete an asset. An Owner on Nova still cannot open the Executive Dashboard.
Custom roles
(Cosmos)
A custom role is a tenant-defined permission set. It specifies:
- An asset scope — self, department, location, or all
- Flags for viewing, editing, and deleting assets
- Whether the role can manage users
- Whether the role can view the dashboard and reports
Manage them at Settings → Roles, Owner only.
Important Custom roles can be defined and stored, but they are not yet enforced. Permission checks still read the system role. Treat custom roles as configurable but not active — assign a system role to control what someone can actually do.
Choosing the right role
Do not default everyone to Admin. Admin can delete assets and categories. Most people who "need to change things" are Managers.
Employee is the right role for technicians. They can update assets, complete maintenance, and check items in and out — everything needed to do the work, without the ability to create or delete records.
Viewer is genuinely read-only. A Viewer cannot see work orders or service records at all, so it is the wrong role for anyone in a maintenance conversation.
There is one Owner. To change who it is, transfer ownership.
When a role change takes effect
Immediately, on the user's next request — not at their next sign-in. Role, plan, and deactivation are re-read from the database on every request.
Common mistakes
Giving Admin to avoid a permission problem. Work out which permission is actually needed. Admin includes deletion.
Expecting a custom role to restrict access today. It will not — enforcement reads the system role.
Assuming Viewers can see everything read-only. Viewers cannot see work orders, service records, or incidents.
Troubleshooting
Settings → Roles isn't visible. Custom roles need Cosmos, and the page is Owner-only.
I created a custom role and nothing changed. Custom roles are stored but not yet enforced. Assign a system role instead.
I can't change someone's role. Role assignment is Owner-only.
A user says they still have old permissions. They should not — changes take effect on their next request. Ask them to reload.
I can't assign someone the Owner role. There is one Owner. Use Transfer ownership.
Related articles
Need Help?
If you have questions not covered in this article, our support team is here to help.
Contact Support