Roles and Permissions

Summary

Torqueflow uses a capability-based permission system. Each staff member is assigned a role, and each role grants a set of capabilities that control what the user can see and do. Owners can view all roles, create custom roles, edit capabilities on custom roles, and delete unused custom roles. System roles (Owner, Manager, Service Advisor, Technician, Kiosk Device) cannot be renamed, deleted, or have their capabilities edited - their capability lists are managed by Torqueflow and stay in sync with the product as new features ship. If you need a system-role-like profile with a tweak, Copy from the system role when creating a new custom role.

Prerequisites

• You are signed in with the settings.roles.manage capability. By default, only the Owner role has this.
• Navigate to Settings in the sidebar.

Permissions

This page requires the settings.roles.manage capability. Users without it are redirected to /settings.

Steps

1. Open the Roles page

Go to Settings > Roles. The page is at /settings/roles.

The page header shows a shield icon, the title Roles, and the subtitle “Manage staff roles and permissions”.

2. Review existing roles

The role list displays all roles for your organisation. Each role card shows:

• Shield icon and role name.
• A System badge (if the role is a built-in system role).
• User count - how many staff members are assigned to this role (e.g. “3 users”).
• Capability count - how many capabilities are granted (e.g. “12 capabilities”). Roles with the wildcard * show “(Full access)”.
• Description - a short summary of the role’s purpose (if set).

System roles are sorted first by their sort order, then custom roles appear alphabetically.

Click any role card to open its edit dialog.

3. Create a custom role

1. Click the Create Role button (top right of the role list).
2. The Create Role dialog opens.
3. Optionally, select a role from the Copy from existing role dropdown to pre-fill capabilities from that role.
4. Enter a Name (required, max 50 characters). For example: “Senior Technician”.
5. Enter a Description (optional, max 200 characters).
6. Select capabilities using the capability selector (see step 5 below).
7. Click Create Role.

A success toast confirms “Role created successfully”. The role appears in the list.

Role names must be unique within your organisation. If a duplicate name is entered, an error message appears: “A role with this name already exists”.

4. Edit an existing role

1. Click the pencil icon on a role card, or click the card itself.
2. The Edit Role dialog opens. For system roles, the dialog shows a System badge and an explanation that the name and capabilities are both managed in code and cannot be edited in the UI. The capability checkboxes are visible but disabled, so you can see what the role grants - they just cannot be ticked or unticked.
3. For custom roles: edit the Name and Description fields as needed.
4. For custom roles only: modify capabilities using the capability selector.
5. Click Save Changes.

When Torqueflow ships a new feature, system roles automatically pick up any new capabilities that belong to them - you do not need to revisit this page after an update. The capability list shown on a system role always reflects what the role grants today, not a stale snapshot from when you signed up.

A success toast confirms “Role updated successfully”.

5. Use the capability selector

Capabilities are grouped by category. The available categories are:

• Finance - invoice, payment, and financial report access.
• Scheduling - appointment and diary management.
• Vehicles - vehicle record access and editing.
• Parts - parts catalogue and ordering.
• Time Tracking - clock-in/out and timesheet features.
• Settings - organisation settings and configuration.
• Audit - audit log viewing.
• AI Assistant - AI chat and analytics access.
• Kiosk - kiosk mode features.

Each category has a collapsible section. To use the selector:

1. Click a category header to expand or collapse it.
2. Tick the All checkbox on the right of a category header to grant all capabilities in that category (this sets a wildcard, e.g. finance.*). Individual checkboxes become disabled when the category wildcard is active.
3. Alternatively, tick individual capabilities. Each has a name and a code (e.g. finance.invoices.create). Hover over the info icon next to a capability name to see its description.

Roles with the global wildcard * (such as Owner) show a message: “Full Access: This role has all capabilities (wildcard *). Individual capabilities cannot be modified.”

6. Delete a custom role

1. Click the bin icon on a custom role card. System roles do not show a delete button.
2. A confirmation dialog appears: “Are you sure you want to delete the role [name]? This action cannot be undone.”
3. Click Delete to confirm.

A success toast confirms “Role deleted successfully”.

Deletion is blocked when:

• The role has users assigned. The dialog shows: “Cannot delete role with assigned users. Reassign X user(s) first.” The Delete button is hidden.
• The role is a system role. No delete button is shown.

7. Assign a role to a staff member

Role assignment is done from the staff member’s profile, not from this page. Go to Settings > Team to change a user’s assigned role.

Expected Outcome

Your organisation has a set of roles - both system and custom - each with a defined set of capabilities. Staff members are assigned roles that control their access throughout Torqueflow. Changes to role capabilities take effect on the next page load for affected users.

Troubleshooting

Problem	Cause	Fix
Roles page redirects to /settings	Your account lacks the settings.roles.manage capability	Ask the Owner to grant you this capability or sign in as Owner
”A role with this name already exists” error	Another role in your organisation has the same name	Choose a different name
Cannot delete a role	The role has users assigned to it	Reassign those users to a different role first, then delete
Delete button missing on a role	It is a system role	System roles cannot be deleted. You can only edit their capabilities
Cannot change the name of a role	It is a system role	System role names are fixed. Create a custom role (with Copy from to pre-fill its capabilities) and edit that instead
Cannot tick or untick capabilities on a system role	System role capabilities are managed in code	Use Copy from when creating a custom role to pre-fill the system role’s capabilities, then adjust them on the new custom role
”Failed to load roles” error	A server error occurred loading role data	Refresh the page. If the problem persists, check your connection

Notes

• Capabilities are seeded automatically. If no capabilities exist in the database, Torqueflow seeds them on first access to this page.
• The wildcard capability * grants unrestricted access to all features. Only assign it to fully trusted roles.
• Changes to a role’s capabilities apply to all users assigned to that role.