Skip to content

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 ​

RouteUse casePermission
GET /permissionsAC1 read the permission catalogorganization.account.manage
GET /rolesAC2 list rolesorganization.account.manage
POST /rolesAC3 create or clone a roleorganization.account.manage
PUT /roles/{roleId}AC4 replace, archive, pause or restore a roleorganization.account.manage
POST /memberships/{id}/role-assignments, PATCH, DELETE /role-assignments/{id}AC5 give, rescope and remove a roleorganization.account.manage (code also accepts identity.team.manage)
GET, PUT /approvals/settingsAC6 where an action needs another member's approvalorganization.account.manage
PUT /memberships/{id}/pinAC7 set the own approval PINthe caller, own membership only
POST /approvals, GET /approvals/can-approveAC8 approve with a PINa session
POST /memberships/{id}/ownership-grantsAC9 make another member an administratororganization-wide administrator + step-up
(permissions, no route of their own)AC10 scoped admin permissionssee 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 ​

StatusCodeWhen
401identity.session_requiredNo live session
403identity.action_forbiddenNo organization-wide permission, or another member's PIN
403tenant.context_rejectedOrganization not the caller's
403identity.role_read_onlyChange to a system role
403identity.approval_deniedAny failed PIN check
403identity.elevation_requiredOwnership grant without step-up
404identity.role_not_foundUnknown or foreign role
404identity.membership_not_foundUnknown or foreign member
409identity.role_in_useArchiving a role active members hold
409identity.approval_not_requiredNo rule asks for approval
422identity.role_permissions_unknownCode outside the catalog
422identity.approval_rule_refusedUnknown permission or foreign structure
422identity.ownership_grant_refusedSelf, inactive member, service identity

Application Foundation in progress. Tracked in issue #13.