User Permissions Overview

User Permissions Overview

This page describes the permissions required for each screen, resource and action in TrackHub, and how the platform decides whether a request is allowed.

Related pages: Security and Identity · Architecture

---

Permission model

TrackHub implements a dual-path authorization model combining Role-Based Access Control (RBAC) with Policy-Based Access Control (PBAC). Every request is checked against the caller's roles and policies to decide whether the required Resource + Action pair is allowed.

graph TB
    subgraph User["Authenticated User"]
        user["User<br/>(JWT Token)"]
    end

    subgraph Assignment["Access Assignment"]
        policies["Policies<br/><i>Fine-grained grants</i>"]
        roles["Roles<br/><i>Grouped permissions</i>"]
    end

    subgraph Authorization["Authorization Check"]
        resource["Resource<br/><i>e.g. Transporters</i>"]
        action["Action<br/><i>e.g. Write</i>"]
    end

    subgraph Result["Decision"]
        granted["✅ Allowed"]
        denied["❌ Denied"]
    end

    user -->|UserPolicy| policies
    user -->|UserRole| roles
    policies -->|ResourceActionPolicy| resource
    roles -->|ResourceActionRole| resource
    resource --- action
    action --> granted
    action --> denied

Loading

How it works

1. A caller sends a request (for example, create a transporter).
2. AuthorizationBehavior in the CQRS pipeline intercepts it.
3. It reads the [Authorize(Resource, Action, PrincipalTypes)] attribute on the command or query.
4. It asks the Security service: "does this principal have permission for Resource X, Action Y?"
5. Security checks the policy path and the role path.
6. Access is granted if either path resolves to a match.

Authorization answers "may this caller do this?" — it says nothing about which tenant was named. That is enforced separately and centrally by AccountScopeBehavior; see Architecture.

Three gates, not one

A request can be refused for three different reasons, and the error tells you which:

Gate	Failure	Meaning
Permission	FORBIDDEN (with requiredResource / requiredAction)	The role/policy check failed
Tenant scope	FORBIDDEN	The request named an account the principal does not own
Feature flag	FEATURE_DISABLED	The account does not have the required feature enabled

---

Actions

Action	Description
Read	View or query the resource
Write	Create new records
Edit	Update existing records
Delete	Remove records
Export	Read a resource's report dataset for export
Execute	Run an operation (job or process)
Custom	Special operations — password update, token refresh, position sync, route planning and sharing

Resources

Group	Resources
Accounts & platform	Accounts, AccountsMaster, AccountFeatures, AccountFeaturesMaster, Administrative, SupportGrants, SettingsScreen
Identity	Users, Profile, Permissions, ServiceClients
Assets	Transporters, TransporterType, Devices, DevicesMaster, ManageDevices, SynchronizedDevices, Groups
GPS integration	Operators, OperatorsMaster, OperatorHealth, OperatorSyncRuns, Credentials, GpsIntegrationDashboard, Positions, PositionHistory, GeocodingProviders, PointsOfInterest
Geofencing	Geofences, Geofencing
Trips	Trips, TripTracking, TollCatalog
Workforce	Drivers
Content & comms	Documents, PublicLinks, Alerts, Notifications
Reporting & ops	Reports, BackgroundJobs, Audit

The …Master variants are the batched, service-identity twins of their tenant-facing counterparts — see Inter-Service Communication.

Roles

Role	Description
Administrator	Full access to all resources and actions
Manager	Account-wide access to operational and administrative resources
User	Group-scoped access, based on assigned responsibilities
Audit	Read-only access to audit data

Roles support a ParentRoleId hierarchy column, but grant resolution does not walk it — ResourceActionRoleReader matches role names exactly. Nothing is inherited.

---

Permissions by screen

Dashboard

The main operational screen: live map and transporter positions.

Resource	Actions	Description
Credentials	Custom, Read	Custom: update an operator's token / refresh token when required
Devices	Read	View devices on the map
Geofencing	Read	View geofence boundaries on the map
Operators	Read	View operator information
Positions	Custom, Read	Custom: update the local transporter position; Read: view positions
Transporter Type	Read	View transporter type classifications

Account Management

Administration of account-level entities: users, groups, transporters, devices, operators, documents and drivers.

Resource	Actions	Description
Accounts	Edit, Read	View and modify account settings
Devices	Delete, Read, Write	Full device lifecycle management
Documents	Delete, Edit, Read, Write	Upload, version, share and retire documents
Drivers	Delete, Edit, Read, Write	Driver registry, qualifications and assignments
Groups	Delete, Edit, Read, Write	Manage user and transporter groups
Notifications	Delete, Edit, Read, Write	Notification rules, subscriptions, templates and the in-app feed
Operators	Delete, Edit, Read, Write	Manage GPS provider operators
Permissions	Read	View assigned permissions
Transporters	Delete, Edit, Read, Write	Manage vehicles and assets
Users	Custom, Delete, Edit, Read, Write	Custom: update a user's password

Notifications grants are held by all portal roles, because the self-service surfaces (feed, mark-as-read, own subscriptions) need them. Rule, template and delivery administration is therefore enforced as privileged inside the writers rather than by the grant alone.

GPS Integration

Resource	Actions	Description
GPS Integration Dashboard	Read	The integration overview screen
Operator Health	Read	Operator health snapshots and history
Operator Sync Runs	Read	Sync-run telemetry (also read by the status page's Manager/Administrator tier)
Synchronized Devices	Read	Devices known to each provider
Credentials	Custom	Manual sync and connectivity ping

Geofences

Resource	Actions	Description
Geofences	Delete, Edit, Read, Write	Full geofence lifecycle management

Trip Management

The /tripManager dispatch board. Gated by the trip-management account feature and offered to User principals only.

Resource	Actions	Description
Toll Catalog	Read	Browse toll stations, tariffs and vehicle classes (read-only for non-administrators)
Trip Tracking	Read	View trip tracking data
Trips	Custom, Delete, Edit, Export, Read, Write	Custom: plan route, share trip, revoke share. Export: trip / stop / POD / toll report data

Public Trip Tracking

The customer-facing tracking page is anonymous — it is opened with a share link rather than a platform session, so it requires no resource permission. What the recipient sees is controlled per share by the trip_shares disclosure flags (driver name, vehicle, live position, stop detail, POD summary, route), not by RBAC. Every flag defaults to false; a disclosure flag fails closed.

Reports

Resource	Actions	Description
Reports	Read	Generate and download reports

The catalog itself is governed: getReports filters server-side by the caller's account features and role, and Reporting re-enforces that metadata at execution time. A hidden report invoked directly by code returns 403 or 404. See Reporting.

Profile

Resource	Actions	Description
Profile	Edit, Read	View and update own profile

System Administration

Platform-level administration.

Resource	Actions	Description
Accounts	Edit	Modify any account in the platform
Administrative	Edit, Read, Write	Create accounts and manager users; background job status; announcement CRUD
Permissions	Delete, Write	Manage permission assignments
Service Clients	Delete, Edit, Read, Write	Register service clients and their resource grants
Support Grants	Delete, Read, Write	Time-boxed support access to an account
Toll Catalog	Delete, Edit, Write	Maintain the platform toll station / tariff / vehicle class catalog
Transporter Type	Edit, Read, Write	Manage the transporter type catalog
Users	Delete, Write	Manage users across accounts

Platform Status

/status is a public route with three tiers:

Tier	Sees	Gate
Anonymous	Service tiles, active announcements	none
Manager or Administrator	Additionally the GPS-synchronisation (SyncWorker) tile	OperatorSyncRuns/Read
Administrator	Additionally the background-jobs table and announcement CRUD	Administrative/Read, Administrative/Write

---

Complete permissions matrix

Screen	Resource	Delete	Edit	Read	Write	Custom
Dashboard	Credentials			✅		✅
	Devices			✅
	Geofencing			✅
	Operators			✅
	Positions			✅		✅
	Transporter Type			✅
Account Mgmt	Accounts		✅	✅
	Devices	✅		✅	✅
	Documents	✅	✅	✅	✅
	Drivers	✅	✅	✅	✅
	Groups	✅	✅	✅	✅
	Notifications	✅	✅	✅	✅
	Operators	✅	✅	✅	✅
	Permissions			✅
	Transporters	✅	✅	✅	✅
	Users	✅	✅	✅	✅	✅
Geofences	Geofences	✅	✅	✅	✅
Trip Mgmt	Toll Catalog			✅
	Trip Tracking			✅
	Trips	✅	✅	✅	✅	✅
Reports	Reports			✅
Profile	Profile		✅	✅
System Admin	Accounts		✅
	Administrative		✅	✅	✅
	Permissions	✅			✅
	Service Clients	✅	✅	✅	✅
	Toll Catalog	✅	✅		✅
	Transporter Type		✅	✅	✅
	Users	✅			✅

Export has no column above. It is granted where a report dataset is read — notably Trips/Export, held by the Manager role and the Reporting service client.

Trip Management notes

• The default role matrix is not identical for the two non-administrator roles. Manager gets Trips Read/Write/Edit/Delete/Export/Custom, TripTracking Read and TollCatalog Read. User gets Trips Read/Write/Edit/Custom and TollCatalog Read only. Administrator keeps grant-all.
• Trips/Custom covers planTripRoute, shareTrip and revokeTripShare.
• TollCatalog Write/Edit/Delete is deliberately withheld from Manager and User — the toll catalog is platform reference data, so non-administrators can read stations, tariffs and vehicle classes but never create, edit or delete one.
• TripTracking/Custom (processTripPositions, the Router/SyncWorker position feed) is a service-client grant only and is never assigned to a role.

---

Implementation

Commands and queries declare their requirement as an attribute:

[Authorize(Resource = Resources.Transporters, Action = Actions.Write)]
public readonly record struct CreateTransporterCommand(TransporterDto Transporter)
    : IRequest<TransporterVm>;

AuthorizationBehavior enforces it before the handler runs:

Request → Logging → Validation → Authorization → AccountScope → Caching → RateLimiting → Handler
                                       ↑
                                Checks [Authorize]
                                via IIdentityService

Resource and action names are the constants in Common.Domain.Constants.Resources and Common.Domain.Constants.Actions — never string literals at the call site.