---
url: /reference/ACCESS_CASE_MATRIX.md
---
# Access Case Matrix

One row per behavioral case for the use cases of
[`ACCESS_USE_CASES.md`](ACCESS_USE_CASES.md), cited the same way as the other
case matrices and verified by `npm run lint:case-matrix`.

***

## Totals

|---|---|
|---|---:|
| Use cases | 9 |
| Per-case scenario rows | 46 |
| Per-case scenario rows proven | 46 |
| Cross-cutting invariants | 2 (2 proven) |
| Gaps | 0 |

***

## Roles and permissions

### AC1 — Read the permission catalog

| Case | Expected answer | Proving test |
|---|---|---|
| Grouped by module with the risk level of each permission | `200` | `test/e2e/roles-catalog.e2e-spec.ts` › `lists the permission catalog grouped by module with the risk level of each permission` |

### AC2 — List roles

| Case | Expected answer | Proving test |
|---|---|---|
| System roles read only, organization roles with member count | Never another organization's roles | `test/e2e/roles-catalog.e2e-spec.ts` › `lists system roles as read only and organization roles with their member count, never another organization roles` |
| `include=permissions` | Adds the permission codes | `test/e2e/roles-catalog.e2e-spec.ts` › `adds the permission codes of every role when asked with include=permissions` |
| Archived roles | Hidden unless asked by status | `test/e2e/roles-catalog.e2e-spec.ts` › `hides archived roles unless they are asked for by status` |
| Unknown query parameter, status or include | `400` | `test/e2e/roles-catalog.e2e-spec.ts` › `answers 400 for an unknown query parameter, status or include` |

### AC3 — Create a role

| Case | Expected answer | Proving test |
|---|---|---|
| Create with a permission set | `201`, whole role, one audit record | `test/e2e/roles-create.e2e-spec.ts` › `creates a role with a permission set, answers it whole and leaves one audit record with the permission codes` |
| Clone a system role or an organization role | Permission set copied under a new name | `test/e2e/roles-create.e2e-spec.ts` › `clones the permission set of a system role and of a role of the organization under a new name` |
| Role to clone unknown or foreign | `404 identity.role_not_found` | `test/e2e/roles-create.e2e-spec.ts` › `answers 404 identity.role_not_found when the role to clone is unknown or belongs to another organization` |
| Permission code outside the catalog | `422 identity.role_permissions_unknown` | `test/e2e/roles-create.e2e-spec.ts` › `answers 422 identity.role_permissions_unknown for a permission code the catalog does not hold` |
| Member without organization administration | `403 identity.action_forbidden`, denial audited | `test/e2e/roles-create.e2e-spec.ts` › `refuses a member without organization administration with 403 identity.action_forbidden, audits the denial and creates nothing` |

### AC4 — Replace, archive, pause or restore a role

| Case | Expected answer | Proving test |
|---|---|---|
| Replace name, description and permission set | Before and after audited | `test/e2e/roles-change.e2e-spec.ts` › `replaces the name, the description and the whole permission set, and audits the before and after` |
| Unchanged definition | Same role, nothing written | `test/e2e/roles-change.e2e-spec.ts` › `answers the same role and writes nothing when the definition is unchanged` |
| Archive a role an active member holds | `409 identity.role_in_use` until the member lets go | `test/e2e/roles-change.e2e-spec.ts` › `refuses to archive a role an active member holds with 409 identity.role_in_use, then allows it once the member lets go` |
| System role | `403 identity.role_read_only`, also when the body changes nothing | `test/e2e/roles-change.e2e-spec.ts` › `refuses a system role with 403 identity.role_read_only even when the body changes nothing` |
| Unknown permission code | `422`, the role stays as it was | `test/e2e/roles-change.e2e-spec.ts` › `answers 422 identity.role_permissions_unknown for a code the catalog does not hold and keeps the role as it was` |

## Approvals

### AC6 — Approval settings

| Case | Expected answer | Proving test |
|---|---|---|
| Never set | Approvals off, no rule | `test/e2e/approval-settings.e2e-spec.ts` › `answers approvals off and no rule for an organization that never set them` |
| Replace the set | A rule left out is withdrawn, a kept one untouched, a new one added | `test/e2e/approval-settings.e2e-spec.ts` › `replaces the set: a rule left out is withdrawn, a rule kept is untouched and a new rule is added` |
| Unknown permission or foreign structure | `422 identity.approval_rule_refused`, old settings kept | `test/e2e/approval-settings.e2e-spec.ts` › `answers 422 identity.approval_rule_refused for an unknown permission and for a business unit or outlet of another organization, and keeps the old settings` |
| Threshold | Kept when repeated, changed when it differs, cleared when left out | `test/e2e/approval-settings-thresholds.e2e-spec.ts` › `keeps a threshold across a save that repeats it, changes it when it differs and clears it when it is left out` |
| Rule of an outlet group | Read as that group, never as an organization-wide rule | `test/e2e/approval-settings-thresholds.e2e-spec.ts` › `reads a rule of an outlet group as that group and never as an organization-wide rule` |
| Outlet group of another organization | `422 identity.approval_rule_refused` | `test/e2e/approval-settings-thresholds.e2e-spec.ts` › `answers 422 identity.approval_rule_refused for an outlet group of another organization` |

### AC7 — Own approval PIN

| Case | Expected answer | Proving test |
|---|---|---|
| Set the PIN | `204`, hash stored, the audit record has no PIN | `test/e2e/member-pin.e2e-spec.ts` › `stores a hash the database verifies, answers 204 with no body, and audits the fact without the pin` |
| Another member's PIN | `403 identity.action_forbidden`, nothing stored | `test/e2e/member-pin.e2e-spec.ts` › `refuses to set the pin of another member with 403 identity.action_forbidden and stores nothing` |
| Logs | The PIN never reaches the application logs | `test/e2e/member-pin.e2e-spec.ts` › `never writes the pin of a failed or a successful request to the application logs` |

### AC8 — Approve an action with a PIN

| Case | Expected answer | Proving test |
|---|---|---|
| Grant | `201` with id and time to live, audited without the PIN | `test/e2e/approvals.e2e-spec.ts` › `grants an approval to the requester, answers 201 with its id and time to live and audits it without the pin` |
| Action key with a NUL character | `400` before any PIN is checked | `test/e2e/approvals.e2e-spec.ts` › `answers 400 when the action key holds a NUL character, before any pin is checked` |
| Head office action with a payload hash | Default time to live | `test/e2e/approvals.e2e-spec.ts` › `grants a head office approval bound to a payload hash, with the default time to live` |
| Every wrong approver case | The same `403 identity.approval_denied` | `test/e2e/approvals.e2e-spec.ts` › `answers 403 identity.approval_denied alike for a wrong pin, an unknown approver, an approver of another organization, an approver without a pin and an approver without the permission` |
| Five wrong PINs | The pair is locked, even the right PIN is refused | `test/e2e/approvals.e2e-spec.ts` › `counts wrong pins even though they are refused: five of them lock the pair and the right pin is then refused too` |
| No rule asks for approval | `409 identity.approval_not_required`, nothing granted | `test/e2e/approvals.e2e-spec.ts` › `answers 409 identity.approval_not_required when no active rule asks for it, and grants nothing` |
| No session, foreign organization | `401`, `403 tenant.context_rejected` | `test/e2e/approvals.e2e-spec.ts` › `answers 401 without a session and 403 tenant.context_rejected for an organization the caller does not belong to` |
| Can the caller approve | Owner with a PIN can; no permission or no PIN cannot | `test/e2e/approvals.e2e-spec.ts` › `tells a caller whether they can approve: an owner with a pin can, a member without the permission or a pin cannot` |

## Administrators

### AC9 — Make another member an administrator

| Case | Expected answer | Proving test |
|---|---|---|
| Grant | Second administrator, the first kept, one audit record with the reason | `test/e2e/ownership-grants.e2e-spec.ts` › `makes a second member an administrator, keeps the first one and audits it once with the reason` |
| Replay | Same answer, nothing written again; other request with the key is refused | `test/e2e/ownership-grants.e2e-spec.ts` › `replays the same key and request with the same answer, writing and auditing nothing again, and refuses the key with another request` |
| The new administrator | May grant the role in turn | `test/e2e/ownership-grants.e2e-spec.ts` › `lets the new administrator grant the role in turn` |
| Step-up and key | Both required | `test/e2e/ownership-grants.e2e-spec.ts` › `requires a live step-up elevation and an Idempotency-Key` |
| Caller or inactive member | `422 identity.ownership_grant_refused` | `test/e2e/ownership-grants.e2e-spec.ts` › `refuses the caller themselves and an inactive member with 422` |
| Unknown or foreign member | The same `404`; malformed id `400` | `test/e2e/ownership-grants.e2e-spec.ts` › `answers an unknown and a foreign membership with the same 404 and a malformed id with 400` |
| Caller not an organization-wide administrator | `403` | `test/e2e/ownership-grants.e2e-spec.ts` › `refuses a member who is not an organization-wide administrator, whoever the target is` |
| Other organization, anonymous | Refused | `test/e2e/ownership-grants.e2e-spec.ts` › `refuses a tenant context of another organization and an anonymous caller` |
| Administrator role held for an outlet group | Not administration; target stays without it | `test/e2e/ownership-grants-group-scope.e2e-spec.ts` › `refuses a member whose administrator role is held only for an outlet group and leaves the target without administration` |

### AC10 — Scoped administration permissions

| Case | Expected answer | Proving test |
|---|---|---|
| `organization.structure.view` | Reads the structure and nothing else | `test/e2e/scoped-admin.e2e-spec.ts` › `lets organization.structure.view read the structure and nothing else, while the owner keeps reading it` |
| `organization.structure.manage` | Changes and reads the structure, manages no team | `test/e2e/scoped-admin.e2e-spec.ts` › `lets organization.structure.manage change the structure, read it and manage no team` |
| No structure permission | Refused on every route | `test/e2e/scoped-admin.e2e-spec.ts` › `refuses a member with no structure permission whatever the route` |
| `identity.team.manage` | Runs the team, none of the structure | `test/e2e/scoped-admin.e2e-spec.ts` › `lets identity.team.manage run the team and nothing of the structure` |
| `organization.account.manage` | Superset of both | `test/e2e/scoped-admin.e2e-spec.ts` › `keeps organization.account.manage as the superset of both` |

## Cross-cutting invariants

| Invariant | Expected answer | Proving test |
|---|---|---|
| A role that grants organization administration is never given by role assignment | `403`, refusal audited | `test/e2e/memberships-role-assignment.e2e-spec.ts` › `never makes anyone an administrator: a role that grants organization administration is refused with 403 and the refusal is audited` |
| Role assignment needs organization-wide administration | A business-unit administrator is refused | `test/e2e/memberships-role-assignment-access.e2e-spec.ts` › `refuses a member who administers only one business unit, because giving a role needs organization-wide administration` |
