Permissions & Feature Flags
TheGarageOS has two complementary access systems — feature flags (workspace → subscription) and role permissions (user → role). Together they decide what each user sees and what they can do.
Feature flags
Every feature in the platform is either:
- A parent — an organizational umbrella (Jobs, CRM, Inventory, …).
- A child — an actual gatable, sellable module (Jobs Core, Quotations, Inventory Vendor Management, …).
Each child feature is independently toggleable, globally and per-tenant, with real-time cache invalidation (changes propagate to running services in under a second, with zero DB hits on the request hot path).
In the UI, disabled features are hidden from the navigation and
return 402 Payment Required from the API.
Where they show up
- Sidebar — nav groups disappear when their feature is disabled.
- Dashboard — widgets appear only if the relevant feature is on AND the user has read permission.
- API — endpoints reject requests for disabled features.
This is also the pricing / packaging mechanism — different subscription tiers enable different feature sets.
Role permissions
Every user has exactly one role. Every role has a set of permissions.
A permission is a triple:
feature_slug :: sub_feature :: action
For example:
| Permission | What it allows |
|---|---|
inventory_vendor_management :: vendors :: read | View the vendors list. |
inventory_vendor_management :: vendors :: write | Create, update, deactivate vendors. |
crm_customer :: customers :: write | Create and update customers. |
jobs_core :: jobs :: read | View jobs. |
jobs_core :: jobs :: write | Create and update jobs. |
jobs_core :: jobs :: transition | Transition job status (FSM). |
jobs_payments :: payments :: record | Record a payment against a job. |
user_management :: users :: invite | Invite new users. |
role_management :: roles :: write | Create / update / delete custom roles. |
System roles
The platform ships six immutable system roles:
| Role | Description |
|---|---|
owner | Full access. Only owner can deactivate workspace. |
admin | Full access except workspace deactivation. |
manager | Operational + reporting access. |
staff | Day-to-day operations (CRUD without admin). |
mechanic | Bay floor + assigned jobs. |
viewer | Read-only. |
System roles are immutable — you cannot delete or rename them, but you can use them as templates when building custom roles.
Custom roles
Build your own roles with exactly the permissions you need. Bulk permission assignment is supported via a permission matrix.
Custom roles can be deleted, but only if no active user holds the role.
Self-protection
A few invariants the system enforces for you:
- You cannot change your own role (prevents lock-out).
- You cannot deactivate yourself (prevents lock-out).
- Only the owner can deactivate the workspace.
- An owner cannot be deactivated by anyone (the owner must transfer ownership first, or use the dedicated transfer flow).
Tips
- Start with system roles — most shops fit with owner / admin / mechanic / viewer.
- Custom roles grow with you — when a service advisor needs invoice-write but not job-transition, build them a role.
- Permissions are server-enforced — the UI may hide buttons for cleaner UX, but the backend is the source of truth.
See Settings & Branding for how to configure users and roles in the app.