Skip to main content

Auth, RBAC & Data-Scoping

The platform serves five persona families with very different rights, plus a data-scoping requirement from the notes: "managers see across vendors, or only the vendor assigned to them." RBAC alone (what actions) is not enough — we also enforce row-level scope (which records).

Identity​

  • Auth provider: central auth in the BFF/gateway issuing short-lived JWT access tokens + rotating refresh tokens; sessions cached in Redis.
  • One identity, many roles: a user can hold multiple roles (e.g. an admin who is also a dealer). Tokens carry roles[] and a scope claim.
  • MFA for admin/manager/finance roles.
  • Per-tenant: identities are isolated per tenant deployment.

Roles (RBAC)​

RolePersonaCan do
customerCustomershop, own assets/warranty, raise complaints, AMC, loyalty
dealerChannel partnerorder, ledger, targets, leads, own loyalty
distributorChannel partner (tier)dealer rights + downstream dealers in territory
technicianField workforceassigned jobs, job close-out, van stock
service_partner_adminService partner orgmanage own technicians + assigned jobs
managerAdmin (scoped)sales/targets/service oversight within scope
marketing_adminAdminCMS, campaigns, promotions, testimonials
finance_adminAdmininvoices, GST, payouts, reconciliation, ledgers
service_headAdminFSM dispatch, SLA, AMC, technician analytics
super_adminAdmineverything within the tenant

Permissions are capability-based (e.g. order:read, ticket:assign, ledger:write); roles bundle capabilities. Enforced via NestJS guards + Medusa admin permissions.

Data-scoping (row-level)​

A scope constrains which records a role can see/act on, independent of capability. Scope dimensions:

DimensionExample
region / zoneNorth zone, TN circle
channelPartnerIdsthe specific dealers assigned to a manager
servicePartnerIda service-partner admin sees only their org
selfa dealer/customer sees only their own records

Worked example — the manager case​

  • A manager token carries either scope: { all: true } or scope: { channelPartnerIds: [...] , regions: [...] }.
  • Every DMS / analytics query is wrapped by a scope filter in a NestJS interceptor — the query layer injects the scope predicate so a developer cannot accidentally return out-of-scope rows.
  • The same scope is applied to BI dashboards so totals/aggregations only reflect in-scope data.

Enforcement layers​

  1. AuthN at gateway (valid token, tenant match).
  2. Capability guard (does the role permit the action?).
  3. Scope interceptor (row-level filter injected into every read/write).
  4. Audit log on all mutations (who/what/when/before-after).

Rules for contributors​

  • Never trust client-supplied channelPartnerId/region for scoping — derive scope from the token.
  • All DMS/FSM/analytics repositories must go through the scoped query layer; raw unscoped queries are forbidden in those domains.
  • Capability + scope are both required; passing one is not enough.
  • See Security for session, secret, and transport rules.