3. Authorization, roles and approvals

3.1 Role abbreviations

Abbr.	Role code	Notes
PSA	PLATFORM_SUPER_ADMIN	Bypasses most role checks; still subject to MFA and fresh-auth rules on step-up actions.
CSA	CLIENT_SYSTEM_ADMIN	Tenant administrator.
PA	PROGRAMME_ADMIN
SCA	STATE_COORDINATOR_ADMIN	Can approve finance_application decisions (committee).
IA	INSTITUTION_ADMIN
FEO	FINANCE_ENTRY_OFFICER	Enters transactions and requests corrections.
FA	FINANCE_APPROVER	Approves and rejects transactions; finance committee decisions.
MA	MONITORING_ANALYST	Read and some write access to monitoring resources and reports.
AC	AUDITOR_COMPLIANCE	Read-only in the domain policy.
EDV	EXECUTIVE_DONOR_VIEWER	Read-only.
IV	INVESTOR_VIEWER	Read-only.
SUP	SUPPORT	Read-only.

The domain policy treats AUDITOR_COMPLIANCE, EXECUTIVE_DONOR_VIEWER, INVESTOR_VIEWER and SUPPORT as read-only roles.

3.2 Authorisation layers

1. Role matrix (authorize()): a per-role, per-resource-kind write permission map; approve, reverse, refund, payout, configure, export are finance or configuration actions.
2. Scope (ABAC): records carry programmeId, stateId, sapzId, institutionId. Generic list queries filter by the actor's scope arrays. Some resources use relation-based data scope (for example, a case register is visible only through its financing case).
3. Saved role policies (permission_policies): consulted only by the finance-application, financing-case and decision routes (actorPolicyPermits). The generic resource route does not consult them.
4. Row-level security in PostgreSQL is the final tenant isolation boundary (withTenantDatabase).

3.3 Maker-checker

• Finance transactions: the creator cannot approve or reject their own transaction (MAKER_CHECKER_VIOLATION, 403). PSA is exempt.
• Corrections (reversal, refund): created as PENDING_APPROVAL and need an approval through /approve, subject to the same maker-checker rule.
• Committee decision on a finance application: the requester of the pending approval and the applicant cannot decide (MAKER_CHECKER_REQUIRED, 403). PSA is not exempt here.
• Financing case creation: requires a completed committee approval with a recorded decider.