Roles & Permissions
Managing custom roles, permission sets, and access control
ServiceCortex uses a role-based access control (RBAC) system to manage what each team member can see and do. Every member is assigned either a built-in system role or a custom role that defines their permissions.
System roles
Four built-in roles are available by default, ordered from most to least privileged:
| Role | Description |
|---|---|
| Owner | Full system access with all permissions. Cannot be restricted. |
| Administrator | Full access to all business operations including billing, analytics, and catalog management. |
| Staff | Standard team member with operational access to jobs, appointments, proposals, clients, and invoices. |
| Contractor | Limited access to own assigned work only. Can view and edit their own appointments, jobs, and time entries. |
Permission model
Permissions follow a resource-action-scope pattern:
- Resource -- the entity being accessed (e.g., job, client, invoice, appointment).
- Action -- what the user can do: view, edit, or delete.
- Scope -- which records the action applies to:
own(only records assigned to the user) orany(all records in the workspace).
Permission implication rules simplify configuration:
- delete implies edit, which implies view -- a user who can delete can also edit and view.
- any implies own -- a user who can view any record can also view their own.
For example, an Administrator with job:delete permission automatically has job:edit and job:view as well.
System role permissions
| Permission area | Owner | Admin | Staff | Contractor |
|---|---|---|---|---|
| Jobs | All | All | View/Edit (any) | View/Edit (own) |
| Appointments | All | All | View/Edit (any) | View/Edit (own) |
| Proposals | All | All | View/Edit (any) | View (own) |
| Clients | All | All | View/Edit | View |
| Invoices | All | All | View | -- |
| Time tracking | All | All | View/Edit (any) | View/Edit (own) |
| Catalog & Pricing | All | All | View | -- |
| Analytics | All | View | -- | -- |
Custom roles
When the built-in roles do not match your team structure, create custom roles with a specific set of permissions.
Creating a custom role
Navigate to Settings > Roles and click New Role. Configure:
| Field | Description |
|---|---|
| Name | A unique machine-friendly identifier (auto-formatted to lowercase with hyphens). |
| Display Name | The human-readable name shown in the UI. |
| Description | An optional description of the role's purpose. |
| Color | An optional colour for visual identification. |
| Permissions | The set of permissions granted to users with this role. |
| Sort Order | Controls where this role appears in lists (default: 100). |
Role names must be unique within your organisation. Names are automatically normalised -- "Team Lead" becomes team-lead.
Assigning roles
Each team member can have either a system role or a custom role, but not both. To change a member's role:
- Go to Settings > Team Members.
- Select the member.
- Choose either a system role from the dropdown or a custom role.
When a role is updated, the RBAC cache is cleared and the member's permissions are refreshed in real time. The member's UI updates immediately to reflect their new access level.
Editing custom roles
You can update a custom role's permissions at any time. Changes take effect immediately for all members assigned to that role. A cache invalidation notification is sent to ensure all active sessions refresh.
Deleting custom roles
A custom role can only be deleted if no team members are currently assigned to it. If members are still using the role, you must reassign them to a different role first.
Permission scopes in practice
The scope system determines record visibility:
- A Staff member with
appointment:view:anysees all appointments on the schedule. - A Contractor with
appointment:view:ownsees only the appointments assigned to them. - Both can edit appointments they have access to, but the Contractor cannot see other team members' schedules.
This scoping applies consistently across jobs, proposals, time entries, and other resources.
What's Next
- Configure your organisation settings and branding.
- Set up your dashboard with widgets tailored to each role.
- Manage team members and invite new users.