Itinera — Roles & Permissions

Last updated: February 24, 2026

Role Overview

Role	Scope	Who they are
SUPERADMIN	Platform-wide	Itinera operator (you) — full access to all companies, all data, billing, platform config
ADMIN	Company-wide	Carrier owner or ops manager — full control within their company, cannot delete routes
DISPATCHER	Company-wide	Day-to-day ops — creates and manages routes, assigns drivers, uploads fuel prices
READONLY	Company-wide	Accountant, auditor, carrier contact — sees everything within their company, changes nothing
OWNER_OPERATOR	Own truck only	Independent contractor — sees their own routes, fuel costs (marked-up price), and earnings
DRIVER	Own assignments only	Employee driver — sees their assigned routes, navigation links, personal fuel/analytics

Action	SuperAdmin	Admin	Dispatcher	ReadOnly	OwnerOperator	Driver
Routes
View all routes	✅	✅	✅	✅	Own only	Own only
Create / edit routes	✅	✅	✅	❌	❌	❌
Cancel routes	✅	✅	✅	❌	❌	❌
Delete routes	✅	❌	❌	❌	❌	❌
Edit COMPLETED/CANCELLED routes	✅	❌	❌	❌	❌	❌
Fleet & Tracking
View live fleet map	✅	✅	✅	✅	Own truck	❌
View deviation alerts	✅	✅	✅	✅	Own truck	❌
Fuel
View fuel stops (real price)	✅	✅	✅	✅	❌	✅
View fuel stops (marked-up price)	—	—	—	—	✅	—
Upload fuel prices	✅	✅	✅	❌	❌	❌
Analytics
Fleet-wide fuel analytics	✅	✅	✅	✅	❌	❌
Own truck analytics	✅	✅	✅	✅	✅ (marked-up)	✅ (real price)
Financial reports / margins	✅	✅	❌	✅	Own earnings only	❌
Reports
Route summary / detail	✅	✅	✅	✅	Own only	Own only
Activity log	✅	✅	❌	✅	❌	❌
Deviation report	✅	✅	✅	✅	Own only	❌
Fuel stops report	✅	✅	✅	✅	Own only	❌
Fuel spend / financial report	✅	✅	❌	✅	Own only	❌
Users & Settings
Manage users (invite, deactivate)	✅	✅ (see constraints)	❌	❌	❌	❌
Manage company settings	✅	✅	❌	❌	❌	❌
Manage all companies	✅	❌	❌	❌	❌	❌
Notifications
Receive all company alerts	✅	✅	✅	✅	Own truck only	❌
Delete notifications	✅	✅	❌	❌	❌	❌

SuperAdmin can assign any role to any user across any company
Admin can assign DISPATCHER, READONLY, OWNER_OPERATOR, DRIVER within their own company only — cannot create or promote other Admins (prevents privilege escalation)
No other role can manage users

Drivers get a simplified mobile-first view, not the full dispatcher dashboard.

Page	Access
Profile	Personal info, password, 2FA
My Routes	Assigned routes (active + past), navigation links, fuel stop recommendations
My Analytics	Personal MPG, fuel history, route history (real prices, not marked up)
Notifications	Alerts about their own truck only

Owner operators see a marked-up price rather than the real network price. Configurable per company and per individual — not hardcoded.

Field	Type	Notes
`id`	uuid PK
`company_id`	uuid FK	Which company this rule applies to
`applies_to_role`	enum	`OWNER_OPERATOR` or `DRIVER`
`user_id`	uuid FK nullable	If set, overrides role-level rule for a specific person
`markup_type`	enum	`FIXED` (e.g. +$0.12) or `PERCENTAGE` (e.g. +5%)
`markup_value`	decimal	The markup amount
`effective_from`	date	When this rule takes effect
`created_at`	datetime

Lookup order: user-level rule → company role-level rule → real price (no rule exists)

Important: Real price always stored internally. Markup applied at display/API response time only — never persisted.

Every time a marked-up price is shown, the real price and applied markup are logged here for margin tracking and dispute resolution.

Fields to add to users when implementing full role system:

Field	Purpose	Phase
`samsara_driver_id`	Links Driver/OwnerOperator to Samsara record for data scoping	Phase 9
`samsara_vehicle_id`	Links OwnerOperator to their specific truck	Phase 8
`company_id`	FK to `companies` table	Phase 8

The JWT/session token must carry companyId once multitenancy is live so every API call can scope queries without an extra DB lookup.

Phase	What gets added	Prerequisite
Roadmap Phase 1	`SUPERADMIN` and `READONLY`	Permission adjustments on existing `requireAuth()` — no schema changes
Roadmap Phase 8	`company_id` scoping + `OWNER_OPERATOR` + `fuel_pricing_rules`	Requires companies table (Better Auth migration)
Roadmap Phase 9	`DRIVER` with simplified portal	Requires Samsara driver ID linking + multitenancy