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 ascopeclaim. - MFA for admin/manager/finance roles.
- Per-tenant: identities are isolated per tenant deployment.
Roles (RBAC)
| Role | Persona | Can do |
|---|---|---|
customer | Customer | shop, own assets/warranty, raise complaints, AMC, loyalty |
dealer | Channel partner | order, ledger, targets, leads, own loyalty |
distributor | Channel partner (tier) | dealer rights + downstream dealers in territory |
technician | Field workforce | assigned jobs, job close-out, van stock |
service_partner_admin | Service partner org | manage own technicians + assigned jobs |
manager | Admin (scoped) | sales/targets/service oversight within scope |
marketing_admin | Admin | CMS, campaigns, promotions, testimonials |
finance_admin | Admin | invoices, GST, payouts, reconciliation, ledgers |
service_head | Admin | FSM dispatch, SLA, AMC, technician analytics |
super_admin | Admin | everything 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:
| Dimension | Example |
|---|---|
region / zone | North zone, TN circle |
channelPartnerIds | the specific dealers assigned to a manager |
servicePartnerId | a service-partner admin sees only their org |
self | a dealer/customer sees only their own records |
Worked example — the manager case
- A
managertoken carries eitherscope: { all: true }orscope: { 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
- AuthN at gateway (valid token, tenant match).
- Capability guard (does the role permit the action?).
- Scope interceptor (row-level filter injected into every read/write).
- Audit log on all mutations (who/what/when/before-after).
Rules for contributors
- Never trust client-supplied
channelPartnerId/regionfor 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.