Appearance
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 and ORGANIZATION_USE_CASES.md. Proof: ACCESS_CASE_MATRIX.md. Diagrams: 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 |