Roles & Permissions

SetldHub implements a deny-by-default RBAC model with 36 fine-grained permissions organized across 12 domains and bundled into 9 launch roles (4 internal, 3 external, 2 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) and purpose-built machine integration roles for API-key principals. The pre-launch legacy role aliases were retired at launch: unknown role names resolve to zero permissions (fail-closed).

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)

The Phase 0 legacy aliases (RANUIAdministrator, onboarding-admin) were retired at launch — the catalog no longer maps them, so they resolve to zero permissions (fail-closed).

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-super-admin / sp-ops-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 9 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.