Scoped permissions: a matrix, not a muddle

What does the capability do?

It gives a franchise network access control that matches its shape, enforced where it cannot be bypassed.

• A generated matrix. Permissions are the product of modules and actions, and every combination becomes an authorisation policy at the API. There are no accidental gaps where a screen exists but no permission governs it.
• Scope-bound roles. A role grant attaches to a network, franchisee, territory, or site. Higher scopes cover everything beneath them; narrower needs get explicit narrow grants. Head-office and franchisee role tiers keep the two sides of the network distinct, and master-franchise access flows through the hierarchy it belongs to.
• Field-level masking. Sensitive fields are masked in the API handlers for roles without the specific permission: a caller without contact-details access receives those fields in a masked form, whatever client they use. Masked rather than blanked, so a consumer sees an explicit mask instead of an empty value it might misread as missing data. Hiding in the UI is a courtesy; masking in the handler is a control.
• Approval as its own action. Approving is a separate action from editing, so workflows that need a second pair of eyes can require them by permission, not convention.
• Your identity provider, your policies. Sign-in supports a variety of methods and typically federates to Microsoft Entra ID or Google, so staff get seamless single sign-on while MFA, conditional access, and joiner-leaver processes stay enforced by the identity platform your organisation already governs, not reimplemented in the product.
• A tested catalogue. One translatable catalogue defines what every permission unlocks, mirrored across the API and the admin in every language, with tests that fail the build when the catalogue and the code drift.

Why the tested catalogue is unusual

Permission systems rot socially: keys accumulate, labels drift, and eventually nobody can say what “Finance.Edit” actually gates, so admins over-grant to be safe. Making the catalogue a single source of truth that CI enforces keeps the meaning of every permission current, which keeps grants minimal, which is the entire point of having permissions.

Why it matters

In a franchise network, access control is commercial trust: franchisees must be certain their data is invisible to their neighbours, and head office must see the network without owning every keyhole. A generated matrix, scoped grants, handler-level masking, and a catalogue that cannot drift make the boundary architectural. It is the same enforcement-at-the-API principle applied across the Franchising module and the platform beneath it.