---
title: "Hierarchy and Delegations"
description: "These features support organizations that need formal reporting structures and the ability to temporarily share permissions between users."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.beelocity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hierarchy and Delegations

These features support organizations that need formal reporting structures and the ability to temporarily share permissions between users.

## Organizational Hierarchy

A **hierarchy** models your organization's reporting structure as a tree. Each **node** represents a position, department, or team — and users are assigned to nodes to reflect where they sit in the organization.

### Example Structure

```
CEO
├── VP Operations
│   ├── Warehouse Manager — Algiers
│   ├── Warehouse Manager — Oran
│   └── Logistics Coordinator
├── VP Finance
│   ├── Head of Accounting
│   └── Financial Controller
└── VP Sales
├── Regional Manager — East
└── Regional Manager — West
```

### Why Use a Hierarchy

The hierarchy serves several purposes within Beelocity's access control:

| Purpose                       | How it works                                                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scope-based access**        | A manager can be granted access to all records created by anyone in their subtree — everyone who reports to them, directly or indirectly. A VP Operations would see records from all three people under them. |
| **Organizational visibility** | Hierarchy nodes can be referenced in [policies](policies.html) and [row access rules](row-access-rules.html) for dynamic, structure-aware access control.                                                         |
| **Approval routing**          | Purchase orders or adjustments can be routed to the user's direct manager for approval, following the tree upward.                                                                                            |
| **Reporting structure**       | The hierarchy gives everyone a clear picture of who reports to whom, useful for both access control and day-to-day communication.                                                                             |

### Setting Up the Hierarchy

1. Go to **Settings → Hierarchy** to create the tree structure.
   - Create top-level nodes first (e.g., "CEO", "VP Operations").
   - Add child nodes under each parent to build out the tree.
   - Each node has a **name**, an optional **type** (department, division, team, position), and a **parent** node.
- **Path** and **Depth** are filled in for you from the parent you pick, and shown read-only. You never type them. Renaming a node, or moving it to a different parent, updates everything beneath it automatically.
   - Two nodes under the same parent cannot have names that reduce to the same path — "East Region" and "east region" collide. If that happens the save is refused and you are asked for a more distinct name.
   - A node cannot be moved underneath one of its own children; those options are hidden from the parent picker.

2. Go to **Settings → User Assignments** to place users in the tree.
   - Assign each user to one or more nodes.
   - Optionally mark a user as the **manager** of a node — this is the person who holds that position or leads that team.
- **You cannot place yourself in the tree.** Because being a manager grants visibility over everything beneath a node, assigning yourself would be a way to widen your own access. Someone else has to do it: an organization owner, or a colleague who manages assignments. Owners are exempt, since they already see everything.

A user can be assigned to multiple nodes (e.g., someone who manages two teams). Nodes without users are valid — they represent unfilled positions or organizational placeholders.

## Delegations

A **delegation** is a time-bound grant where one user shares some or all of their permissions with another user. Think of it as a formal "out of office" handover — the delegating user's permissions are temporarily extended to someone else, with a clear start and end date.

### When to Use Delegations

| Scenario                       | How delegation helps                                                                                                                   |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Vacation coverage**          | A procurement manager going on leave delegates their approval authority to a colleague for two weeks.                                  |
| **Project empowerment**        | A director temporarily gives a team lead elevated permissions to manage a specific initiative without permanently changing their role. |
| **Organizational transitions** | During a reorganization, permissions can be temporarily shared to ensure continuity while roles are being redefined.                   |
| **Training and shadowing**     | A senior staff member delegates permissions to a trainee so they can practice with real data under supervision.                        |

### Creating a Delegation

1. Go to **Settings → Delegations**.
2. Select the **user to delegate to** — the person who will receive the permissions.
3. Choose **which permissions** to share — you can delegate all of your permissions or select a specific subset.
4. Optionally scope the delegation to a specific **hierarchy node** — this limits the delegation to records within that part of the organization tree.
5. Set a **start date** and **end date** — the delegation is only active during this period.
6. Optionally add a **reason** — document why the delegation exists (e.g., "Covering Fatima's parental leave, March 1-31").

### How Delegations Work

- The delegated user gains the selected permissions for the specified period **in addition to** their own permissions. Their existing access is not affected.
- When the end date passes, the delegated permissions are **automatically revoked** — no manual cleanup needed.
- Revoking early takes effect immediately, and it reaches everything downstream: if the person you delegated to passed some of it on, those onward delegations are revoked with it.
- Whether someone can pass a delegation on at all is set by **max redelegation depth**. Leave it at 0 — the default — and they can use the permissions but not hand them to anyone else. Each hop must be smaller than the last, so a chain always ends.
- Delegations are logged for audit purposes — you can always see who delegated what to whom and when.

Each list narrows on its **filter button** ([Working with lists](../getting-started/working-with-lists.html#narrowing-the-list)): **Hierarchy nodes** by **Type**, **Parent**, **Active** or a depth range; **User assignments** by **Unit**, **User**, **Manager** and **Active** — "the managers of one unit" is two picks; **Delegations** by **Delegator**, **Delegate**, **Scope**, **Active**, a **Valid From** / **Until** window, and by **Status** — the same Active / Revoked / Expired / Inactive reading the row shows, answered by the server from the grant's dates and flags.

## Tips

- **Keep the hierarchy simple** — model your actual reporting structure, not an aspirational org chart. 3-5 levels deep is typical. Excessively deep trees are hard to maintain and reason about.
- **Update assignments when people move** — the hierarchy is only useful if it reflects reality. When someone changes teams or gets promoted, update their node assignment.
- **Always set end dates on delegations** — open-ended delegations defeat the purpose. Even if the end date is far in the future, having one ensures the delegation does not linger indefinitely.
- **Use the reason field** — six months from now, "Covering Ahmed's paternity leave" is much more useful than an unexplained delegation grant.

Source: https://docs.beelocity.com/en/access-control/hierarchy-and-delegations/index.mdx