Access Model

How TotalApp decides who can open an add-on screen: a single source of truth (SSoT), a Level-1 package check, and a Level-2 user-role check — rendered as friendly screens instead of errors.

Single Source of Truth (SSoT)

Every access decision reads from one authoritative place — there are no duplicate or "shadow" permission files that can drift apart:

Question	Read from
Has the tenant activated this add-on package?	`entitlements/entitlements.json` (per tenant) — the same file the admin writes.
What roles & capabilities exist?	`roles/roles.json` (per tenant, all domains in one store).
Which roles does this person hold?	`Employee.assignedRoles[]`.
Is this user an administrator?	The shared admin-status check used everywhere access decisions are made.

Why one store matters

What an administrator activates for a tenant is exactly what the app's access guard reads back — the admin panel and the running app never disagree, because they both point at the same per-tenant files. No separate central mapping to keep in sync.

The Guard — Two Levels

Every add-on screen (Roles, Staff, and all operational master-data screens) passes through a two-level gate rendered inside the app layout, so a blocked screen shows a clean Upsell or Access-Denied panel — never a blank page or a 500 error.

Open add-on screen → Level 1: Package active? → Level 2: User allowed? → Render screen

Level 1 — Package Entitlement (Paywall)

First the guard asks: has this tenant activated the add-on's package? If the package is not in the tenant's active list, the screen is replaced by an Upsell / Upgrade panel:

Upsell screen

"The [Module] module is not included in your subscription. Upgrade your plan or contact your administrator to activate it." — with an Upgrade action.

This is a company-level (tenant) decision, independent of who the individual user is.

Level 2 — User Role (RBAC)

If the package is active, the guard then asks: may this specific user open the module? The answer depends on whether the screen is governance or operational master data:

System / Governance data

Roles and the add-on's Staff Master screen. Restricted to administrators only — these control security, entitlements and team membership.

Operational data

Jobsites, zones, work centers, fields, nodes, assets, catalogs… Open to any user who holds a role in that add-on's domain (or an admin). A site engineer must be able to add a zone without needing a tenant admin.

User	Governance (Roles / Staff)	Operational
Administrator (or local/demo)	Allowed	Allowed
User holding a domain role	403 Denied	Allowed
User without a domain role	403 Denied	403 Denied
Package not active	Paywall (Level 1)	Paywall (Level 1)

Who counts as an administrator?

Administrator status comes from one shared rule used everywhere (the guard, the sidebar, and My Apps), so behaviour is always consistent:

Tenant Admin or System Admin — always administrators.
Local / standalone sessions (onboarding skipped, or no tenant sign-in yet) — treated as administrators so the app is fully usable while you evaluate it. Real tenant users with a normal (non-admin) role are not administrators.

Governance screens are also hidden

For non-administrators, governance screens aren't just blocked on open — their cards are not rendered at all in the sidebar or My Apps. A regular user only ever sees the operational setup relevant to their job.

Frequently Asked Questions

What is the difference between Level 1 and Level 2?

Level 1 is a company decision — has the tenant bought/activated the module. Level 2 is a person decision — does this user have the right to open it. A failed Level 1 shows an Upsell; a failed Level 2 shows Access Denied.

Why can I open every screen locally without assigning any roles?

Local/standalone sessions have no tenant RBAC context yet, so they're treated as admin to keep the app usable. Once you sign in as a real tenant user, the two-level checks apply normally.

Could the admin panel and the app ever show different access?

No. Both read and write the same per-tenant entitlement and role files — there is no separate central store to fall out of sync.