---
url: /reference/ACCESS_USE_CASES.md
---
# Access Administration Use Cases

Roles, the permission catalog, role assignments, approvals, the approval PIN,
ownership grants and the scoped admin permissions. Module: `identity`
(`src/modules/identity/`). Invitations, memberships and sign-in:
[`IDENTITY_CASE_MATRIX.md`](IDENTITY_CASE_MATRIX.md) and
[`ORGANIZATION_USE_CASES.md`](ORGANIZATION_USE_CASES.md). Proof:
[`ACCESS_CASE_MATRIX.md`](ACCESS_CASE_MATRIX.md). Diagrams:
[`SYSTEM_FLOWS.md`](SYSTEM_FLOWS.md) sections 4 and 5.

## 1. What is built

| Route                                                                               | Use case                                            | Permission                                                               |
| ----------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
| `GET /permissions`                                                                  | AC1 read the permission catalog                     | `organization.account.manage`                                            |
| `GET /roles`                                                                        | AC2 list roles                                      | `organization.account.manage`                                            |
| `POST /roles`                                                                       | AC3 create or clone a role                          | `organization.account.manage`                                            |
| `PUT /roles/{roleId}`                                                               | AC4 replace, archive, pause or restore a role       | `organization.account.manage`                                            |
| `POST /memberships/{id}/role-assignments`, `PATCH`, `DELETE /role-assignments/{id}` | AC5 give, rescope and remove a role                 | `organization.account.manage` (code also accepts `identity.team.manage`) |
| `GET`, `PUT /approvals/settings`                                                    | AC6 where an action needs another member's approval | `organization.account.manage`                                            |
| `PUT /memberships/{id}/pin`                                                         | AC7 set the own approval PIN                        | the caller, own membership only                                          |
| `POST /approvals`, `GET /approvals/can-approve`                                     | AC8 approve with a PIN                              | a session                                                                |
| `POST /memberships/{id}/ownership-grants`                                           | AC9 make another member an administrator            | organization-wide administrator + step-up                                |
| (permissions, no route of their own)                                                | AC10 scoped admin permissions                       | see section 2                                                            |

`organization.account.manage` is the administrator permission, held
organization-wide. A refusal is `403 identity.action_forbidden`, audited on
writes.

Not built: no business route consumes an approval yet. Granting one is REST;
`identity.require_approval` (spend it once) is only called in SQL.

## 2. Permissions and visibility

A permission code is `module.resource.action`; the catalog gives each a
`riskLevel`: `standard`, `sensitive` or `critical`. A critical permission
(today `organization.account.manage`) can be put in a role only by a member who
administers the whole organization, and a role that grants it is never offered
by invitation or role assignment. A role is held at a scope (organization,
business unit, legal entity, brand, site, outlet or outlet group) and counts
only inside it.

Three admin permissions: `organization.account.manage` is the superset of
`organization.structure.view/manage` (legal entities, brands, sites, outlets,
outlet groups, schedules, sales channels, at a scope) and `identity.team.manage`
(invite and assign roles, never the administrator role). Held by default:
owner all; manager `structure.view` and `team.manage`.

Visibility follows the permission, not the role name
(`identity.visible_outlet_ids`). System roles (`organization_owner`,
`manager`, `cashier`, `waiter`, `bar`, `kitchen`, `sales_associate`,
`stock_keeper`) are read-only and change only by migration.

## 3. Cases

AC1: answers every active permission grouped by module with `code`, `name`,
`description` and `riskLevel`; not paginated; not audited.

AC2: lists system roles and roles of the organization ordered by name with
`id`, `code`, `name`, `description`, `status`, `readOnly`, `vertical` and
`memberCount`. `status` filters; archived roles are hidden unless asked for.
`include=permissions` adds `permissionCodes`. Not paginated, not cached by ETag.

AC3: body `name`, optional `description`, and exactly one of `permissions`
(codes) or `cloneFromRoleId`. A clone copies the permission set only and
becomes an editable role of the organization with no vertical. `201` with the
whole role. Errors: `422 identity.role_permissions_unknown`,
`404 identity.role_not_found`. Audited as `identity.role.created`.

AC4: either the whole definition (name, optional description, permission set,
which replaces the old one) or only a `status` (`archived`, `inactive`,
`active`), never both. A change that alters nothing writes nothing, not even an
audit record. Errors: `403 identity.role_read_only` for a system role,
`409 identity.role_in_use` when active members still hold the role being
archived, `422 identity.role_permissions_unknown`, `404 identity.role_not_found`.
Audited as `identity.role.updated` or `identity.role.archived`.

AC6: `GET` answers `enabled` (off until an administrator turns it on) and the
active `rules`: a `permissionCode`, optionally one `businessUnitId`, `outletId`
or `outletGroupId`, and optionally a `threshold` (`amount`, `percent` or
`units` with a decimal): approval is asked only above it. `PUT` sets the switch
and replaces the whole rule set; asking for what holds writes nothing. An
unknown permission or foreign structure is `422 identity.approval_rule_refused`.
Audited as `identity.approval_switch.changed` and `identity.approval_rule.changed`.

AC7: four to eight digits; the path membership must be the caller's, or `403`.
Answers `204`. The PIN is hashed by the database, never logged, audited or
answered. Replacing it clears the failed attempts and the lock.

AC8: `POST /approvals` with `approverMembershipId`, `permissionCode`,
`actionKey`, `pin`, optional `outletId`, `payloadHash`, `ttlSeconds` (1 to 900,
default 300). `201` with `approvalId` and `ttlSeconds`; the approval is bound to
the requester, spent once, and audited as `identity.approval.granted`. Every
wrong case (wrong PIN, unknown approver, other organization, suspended, no
permission, no PIN, locked) is the same `403 identity.approval_denied`; five
wrong PINs per pair lock it 15 minutes, ten per approver. No rule asking for it
is `409 identity.approval_not_required`. `GET /approvals/can-approve` answers
whether the caller holds the permission at the outlet, has a PIN and is not
locked; it does not say whether a rule asks.

AC9: an organization-wide administrator gives another active human member the
administrator role, keeping their own. Needs a live step-up
(`x-elevation-token`, else `403 identity.elevation_required`), a `reason` of 1
to 1000 characters and `Idempotency-Key`. Unknown or foreign member: `404
identity.membership_not_found`; the caller, a suspended or ended member and a
service identity: `422 identity.ownership_grant_refused`. A role held only for
an outlet group is not administration. One audit record names grantor, member
and reason.

AC10: `organization.structure.view` reads the structure and nothing else;
`.manage` changes it and manages no team; `identity.team.manage` runs the team
and none of the structure; `organization.account.manage` holds all three.

## 4. Errors

| Status | Code                                | When                                                     |
| ------ | ----------------------------------- | -------------------------------------------------------- |
| 401    | `identity.session_required`         | No live session                                          |
| 403    | `identity.action_forbidden`         | No organization-wide permission, or another member's PIN |
| 403    | `tenant.context_rejected`           | Organization not the caller's                            |
| 403    | `identity.role_read_only`           | Change to a system role                                  |
| 403    | `identity.approval_denied`          | Any failed PIN check                                     |
| 403    | `identity.elevation_required`       | Ownership grant without step-up                          |
| 404    | `identity.role_not_found`           | Unknown or foreign role                                  |
| 404    | `identity.membership_not_found`     | Unknown or foreign member                                |
| 409    | `identity.role_in_use`              | Archiving a role active members hold                     |
| 409    | `identity.approval_not_required`    | No rule asks for approval                                |
| 422    | `identity.role_permissions_unknown` | Code outside the catalog                                 |
| 422    | `identity.approval_rule_refused`    | Unknown permission or foreign structure                  |
| 422    | `identity.ownership_grant_refused`  | Self, inactive member, service identity                  |
