Hierarchy
Model real organizational structure inside an Environment: typed nodes, parent-child rules, and role assignments that cascade down the tree.
Overview
A hierarchy is a tree of typed nodes representing the organizational structure inside an Environment: regions, offices, departments, teams, or whatever shape your customers actually have. Every Environment starts with a single root node (flat RBAC); switching to hierarchy mode lets you add child nodes and assign roles at any depth. The shape is yours to define via the Environment's hierarchy_schema; Canopy enforces the schema on every node create and move and walks the tree at evaluate-time to resolve permissions through inheritance. Hierarchy also runs inside the organizations container: with organizations on, each organization is the top of its own tree and the levels you define hang beneath it. If your tenants are whole companies rather than branches of one, see the Organizations page.
Scope
Hierarchies are scoped to an Environment
Each Environment owns its own independent tree, root node, and hierarchy_schema. Sibling envs in the same Application can carry completely different shapes: development can run hierarchy mode while production stays flat, or both can run hierarchy with different node-type vocabularies. The schema lives on environment.settings, not on the Application.
This is what makes safe iteration possible: you can model an entire org tree in Development, test the evaluator against realistic node depths, and only flip Production over when you're confident the shape holds.
Schema & Node Types
The hierarchy_schema defines the rules your tree has to follow. It lists every node_type a node can be (e.g. region, office, department, team), the allowed_children map (which types can sit beneath which), the max_depth, and the root_node_type. The schema is a prerequisite: define it before your first node create, via PATCH /api/v1/hierarchy-schema from a setup script or the Console's enable-hierarchy wizard; otherwise POST /api/v1/nodes refuses with a 400 ("Hierarchy schema is not configured"). Canopy then validates against the schema on every node create and every node move. An invalid parent-child combination or a move that exceeds max_depth is rejected with a 400 before any data changes.
The schema is mutable via PATCH .../hierarchy-schema, and the one change it refuses is removing a node type that's currently in use. Other changes, to allowed_children or max_depth, govern nodes created or moved afterwards; existing nodes keep their place even where the new rules would not allow them.
Node Operations
Nodes are managed through the standard env-scoped endpoints: create under any valid parent, move to a new parent if the schema allows, and soft-delete a node together with everything beneath it. When a node moves, every assignment at or below it moves with it, and inheritance recalculates automatically; there is no separate publish step.
The Console's Hierarchy page wraps these endpoints behind a drag-and-drop tree editor; client apps can integrate directly via the same routes on the public API surface.
Inheritance & Cascade
When you assign a role to an identity at a node, the role's permissions apply at that node and every descendant. Canopy resolves permissions at evaluate-time by walking up the lineage from the target node to the root, gathering every active assignment along the way (inside an organization, only while the holder's membership there is active), and unioning the permissions:
An identity needs only one assignment at the highest applicable level, with no per-leaf duplication. Assign a Regional Manager role at the North America node and it covers every office, team, and identity beneath it. Move a subtree to a new parent and the assignments come along; the lineage walk picks up the new ancestor's roles automatically.
Reverting to Flat
An Environment in hierarchy mode can collapse back to flat at any time via POST .../revert-to-flat. The operation consolidates surviving assignments at the root node and deletes every non-root node, keeping each surviving assignment's dates rather than activating or extending them, with one exception: an identity holding the same role through several assignments ends up with one that runs from the earliest start to the latest end, which grants the role in any gap between them:
The response includes assignments_moved, assignments_deduplicated, assignments_expired_dropped, assignments_dropped_scoped, nodes_deleted and organizations_preserved so the admin sees exactly what happened. The revert is refused while any Admin Workspace administrator is scoped to a node in the Environment, because deleting the node would silently take that grant away: re-scope those administrators first. The env's hierarchy_schema is cleared and access_model flips to flat only after the assignment consolidation completes. With the organizations container on, the organizations and their memberships stay; only the trees beneath them go, and assignments at those nodes are dropped rather than widened.
Next Step
Tell us how we can improve this guide.