Skip to main content

RBAC — Role-Based Access Control

Every action in ORKSTRA is gated by RBAC. RBAC is not optional — there is no "admin override" or "superuser bypass" mode. Every read, write, and delete is checked against the calling user's permission set at request time.

Overview​

ORKSTRA's RBAC follows the standard subject → action → resource model with one twist: permissions are scoped to a (tenant, company) pair, not globally. A user can be a PROJECT_MANAGER on Company A and an INSPECTOR on Company B without those grants leaking.

Screenshot: User detail screen with role assignments per company

The system ships with 30+ pre-defined roles covering the common construction org chart — project director, project manager, planner, quantity surveyor, finance director, accountant, HSE officer, QA/QC engineer, inspector, document controller, store-keeper, and more. Tenants can also define custom roles.

Key concepts​

Permission. The atomic unit. Each permission is a string like IPC_CREATE or HSE_INCIDENT_VIEW. The current catalogue has 300+ permissions across all modules.

Role. A named bundle of permissions. Roles are tenant-level: every tenant has its own role catalogue, seeded from the system defaults and editable from Admin → Roles.

Role assignment. A (user, role, company) triple. A user can hold multiple roles per company; the effective permission set is the union of all assigned roles.

Scope. Some permissions are further scoped to specific projects, document folders, or BOQ revisions. Project-level scopes are managed under Project → Settings → Team.

Permission seed. On every backend deploy, the permission_seed_service reconciles the in-database catalogue with the code-defined catalogue. New permissions are added; obsolete ones are flagged but not deleted automatically.

Step-by-step: assign a role to a user​

  1. Go to Admin → Users and pick the user.
  2. Click Add role.
  3. Pick the company the role applies to.
  4. Pick the role from the catalogue.
  5. (Optional) Restrict by project — leave blank for company-wide scope.
  6. Click Save. The user's permission cache invalidates immediately and the new grants apply on their next request.

Step-by-step: create a custom role​

  1. Go to Admin → Roles → New role.
  2. Name the role (e.g., Junior Planner) in EN and AR.
  3. Pick a base role to inherit permissions from, or start from scratch.
  4. Tick the permissions you want to grant.
  5. Click Save. The role is immediately available for assignment.

Common tasks​

  • Audit who can do X: Admin → Permissions → search "IPC_APPROVE" lists every role and every user with that permission.
  • Bulk re-assign roles: export user list, edit in Excel, re-upload via Admin → Users → Bulk import.
  • Test as another user: admins can Impersonate with full audit trail.
  • Revoke a role: Admin → Users → [user] → role row → Revoke.

Troubleshooting​

  • "User cannot see a module they just got a role for." — Permission cache is per-session. Ask them to sign out and back in.
  • "403 on an endpoint after a role change." — Same as above. Cache TTL is 5 minutes; sign out forces an immediate refresh.
  • "Custom role lost permissions after a backend deploy." — Check the permission seed report at Admin → Audit → Permission seed runs. Renamed permissions need a manual remap.

Premium add-ons​

The Premium tier adds:

  • 2FA enforcement per role — see RBAC Premium + AI.
  • AI anomaly detection — flag unusual access patterns.
  • Field-level encryption — Fernet-encrypted sensitive columns.

Permission reference (top-level groups)​

ModuleExample permissions
ProjectsPROJECT_VIEW, PROJECT_CREATE, PROJECT_BASELINE_EDIT
BOQBOQ_VIEW, BOQ_IMPORT, BOQ_REVISE
IPCIPC_CREATE, IPC_APPROVE, IPC_CERTIFY
HSEHSE_INCIDENT_REPORT, HSE_PERMIT_ISSUE
AdminUSER_MANAGE, ROLE_MANAGE, TENANT_SETTINGS_EDIT

The full list of 300+ permissions is at Admin → Permissions.

See also: RBAC Premium + AI, Audit Log, Admin guide.