01 · Roles & access

Org units and responsibility keys

Model branches, sites, warehouses, and approval responsibility without handing out global access.

5 min read · updated 28/05/2026

Who can do this

Role	Create order draft	Confirm / dispatch order	Pack order	Record payment	Void invoice	Edit pricing
Owner	Allowed	Allowed	Allowed	Allowed	Allowed	Allowed

Overview

Roles answer what a teammate may do. Org units answer where they may do it, and responsibility keys answer which duty they hold there. Neev combines the three when it resolves an approval stage. If nobody holds the key in the required unit, or more than one person qualifies, the stage stops as blocked work instead of silently choosing the Owner.

Where to find it

There is no dedicated Organization screen in this build. The tenant-scoped controls are exposed by the platform organization service/API; the admin integration uses operations such as createOrgUnit, moveOrgUnit, archiveOrgUnit, and createOrgUnitMembership. Approval recovery remains in Approvals (/approvals).

Key concepts

An org unit is a node in the tenant tree: company, branch, site, warehouse, territory, or department. A company is the root; child units need a parent. Codes are stable, unique among siblings, and use letters, numbers, and hyphens.
A membership places a user at a unit for an effective period. include_descendants extends that place down the tree. scope_mode=all covers every key the user's roles provide; scope_mode=filtered narrows the membership to its listed responsibility keys.
A responsibility key is a stable duty such as org.unit.head, procurement.head, or intake.credit-override. A role must grant the key through its responsibility mapping; membership alone never grants authority.
Holder resolution is downward from the requested unit and respects the user's active membership, role key, and filters. Zero or ambiguous holders are a deliberate refusal/block, not a permission to fall back to a global role.

Common workflows

Create the unit tree

Create the legal entity and company root, then add branches, sites, warehouses, territories, or departments with a parent, code, and name. Keep codes stable: they are used to identify scope and make sibling units unambiguous.

Place a teammate in scope

Create an active membership for the user and unit, choose whether descendants are included, and set all or filtered scope. A filtered membership must list at least one existing responsibility key.

Grant the responsibility

Add the duty to the teammate's role responsibility mapping, then use the membership scope to limit where that duty applies. A user with the key but no membership is not a holder at the unit.

Move or archive a unit

Move a unit when its reporting tree changes; Neev updates the path under the tenant tree. Archive only an empty branch: active children, memberships, locations, or stock must be cleared first.

Fix a blocked approval

In Approvals, read the blocked responsibility key and unit. Add or scope an eligible holder, then use the blocked-stage recovery operation; do not assign an Owner as a shortcut. A stage with an existing seat must be reassigned rather than recovered as seatless.

Role notes

Owner is the documented tenant administrator for organization setup and role configuration. The Owner still needs the same responsibility and org-unit checks to be the holder of a stage; Owner status is not a global approval fallback.

A Manager can be an approval holder when their role grants the responsibility key and their membership covers the unit. Manager is not a platform-admin role by default, so organization and role changes remain an Owner/admin integration task.

Tips & time-savers

Tip

Start at the narrowest unit that matches the real duty. Include descendants for a branch-wide responsibility; use filtered scope when one person should hold only selected keys.

Keep responsibility keys stable and descriptive. Change a user's membership period or filters when the scope changes instead of cloning a role for every branch.

Gotchas

Warning

A role grant without a matching membership does not make someone a holder. Conversely, a broad membership does not create a duty the role does not grant. Removing the last key filter from a filtered membership is refused, and a withdrawn key is orphaned rather than deleted.

Moving a unit can change which memberships resolve at a descendant. Check open approvals after a move. If resolution becomes zero or ambiguous, the engine exposes blocked work with the key and unit so an authorized operator can recover it explicitly.

Custom roles and editing the built-in roles The permission model: keys, layers, and how access is decided Approvals inbox: decide, unblock, and retry work

Was this helpful?