Roles & Permissions

SetldHub implements a deny-by-default RBAC model with 36 fine-grained permissions organized across 12 domains and bundled into 14 roles (6 internal, 5 external, 3 machine). The approach is hybrid: Frontegg assigns coarse roles via the JWT roles[] claim, while a code-owned shared catalog (@setldpay/rbac) maps those roles to granular <entity>:<action> permissions. Both the frontend and backend resolve permissions from the same catalog at runtime, ensuring consistency by construction.

Data scope is orthogonal to permissions. A principal's clientIds and programIds — already carried in the token — determine which data they can see (row-level isolation), while permissions determine which actions they can perform (feature-level gating). The two compose: an action check (403) runs before a scope check (404), so an out-of-scope target never discloses existence.

Every unresolved product question was shipped as a denied cell (no permissive defaults). All 14 numbered decisions are now resolved. The model supports multi-role composition (permissions union across roles), purpose-built machine integration roles for API-key principals, and a phased migration path that avoids locking anyone out during rollout.

The platform surface spans 12 domains. Audience indicates whether the capability is offered to external client users (always composed with their own-client / own-program scope).

Conventions: lowercase snake_case entity, lowercase verb, : separator. R = read, W = mutate.

Coarse roles assigned in Frontegg (delivered as roles[]). Scope (clientIds/programIds) is assigned separately on the Frontegg user / API key and is orthogonal. Permission counts are derived from the shipped catalog.

Internal (SetldPay staff)

External (client-org users)

Machine (non-interactive)

Bounded legacy aliases (Phase 0 migration): onboarding-admin → sp-onboarding , RANUIAdministrator → sp-ops-admin

Role composition (multi-role)

A user may hold multiple roles; effective permissions are the union across them (the roles[] claim is an array; permissionsForRoles unions). Additive-only — there is no deny role, so combining roles only ever grants more.

• Compose, don't duplicate. Keep roles coarse and non-overlapping; assign combinations for "two-hats" users.
• Union can't narrow. To grant someone less than an existing role, define a dedicated narrow role.
• Scope is per-principal. Effective data scope is the token's single clientIds/programIds regardless of role count. The lone exception is the role-driven cross-tenant widener (sp-onboarding / sp-super-admin over the onboarding-card pool).
• Tier-mixing guard (load-bearing). Never assign an internal sp-* role and an external client-* role to the same user. Enforce via assignment governance and by having the cross-tenant widener also gate on internal tokenType (defense in depth).

Interactive matrix showing all 14 roles and 36 permissions. Click a role header to see its full grant set, or click a permission row to see which roles hold it. Use the toolbar to filter by tier, domain, or external-facing permissions.

Every request takes the same path, regardless of how the caller authenticated. Two gates compose, in a fixed order: the action gate answers "may this principal do this at all?" and the scope gate answers "is this row theirs?" — so an out-of-scope target is never revealed to a caller who couldn't act on it anyway.

UI enforcement (advisory)

The frontend derives permissions client-side from the JWT roles[] claim via the shared @setldpay/rbac catalog. A rewritten PermissionsService exposes can(permission) signals that drive route guards, sidebar visibility (requires keys per nav item), and a *spCan structural directive for inline UI elements (buttons, menus, tabs). This layer is advisory — it shapes the user experience but is not a security boundary. A stale catalog at worst shows a button that returns 403; it never grants access.

Backend enforcement (security gate)

A requirePermission preHandler on each route is the real security gate. It resolves effective permissions once per request from the token's roles[] via the same shared catalog, then asserts the route's required permission before the handler runs (403 on denial). This composes with the existing per-service data-scope isolation: permissions answer "may this principal do this action at all?" while scope answers "is this row theirs?" (404). Scoped endpoints return 403 then 404; global-resource endpoints (MCC imports) use the permission gate as their sole control.

Machine-to-machine access (API keys)

Client API keys (spk_ tokens) are first-class authorization principals resolved through the same catalog. Keys carry a roles[] column mapped to purpose-built integration roles (client-integration for read + safe writes, client-integration-ro for read-only reporting). All token types — Frontegg, internal, and API key — resolve permissions identically via permissionsForRoles(). Scope (clientIds/programIds) on the key drives row-level isolation, composing with permissions the same way it does for human principals.