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

# Groups & Roles

> Understand how permissions, autonomy, and approval hierarchies work in H3aven.

To ensure security and process efficiency, H3aven uses a structured permission system based on **Roles** and **Groups**. This system defines who can view, edit, or approve actions within the platform.

## Core Concepts

### Roles

A **Role** is the representation of a specific job title or user function, identified by the user's email address. It is the atomic unit of identity in the system.

* A single user (email) can hold multiple Roles.
* A Role belongs to an Organization (Org).

<Tip>
  **Real-world analogy:** Think of a Role as a "Hat". One person can wear multiple hats (e.g., "Manager" and "Analyst") depending on the task they are performing.
</Tip>

### Groups

A **Group** is a set of Roles granted specific autonomy within a platform process. Groups are primarily used to configure **Approval Flows**.

* **Redundancy:** Different Roles assigned to the same Group share the same power of action.
* **Use Case:** This is ideal for coverage scenarios. If an employee is on vacation, another user with a Role in the same Group can approve the process in their place.

***

## Approval Logic & Hierarchy

Groups are configured within the **Approval Tab** of a process. You can set up the flow in two ways:

1. **Simple Configuration:** No specific order is enforced. Any authorized group can interact.
2. **Ordered Configuration:** A strict sequence of interaction (measurement and evaluation) is enforced.

### Power Accumulation

A powerful feature of H3aven is the accumulation of permissions. Since a user is identified by their email, if they hold multiple Roles across different Groups, their actions effectively count for all those groups simultaneously.

### Example Scenario

Consider a process that requires a chain of approval from three distinct groups: **Analysts**, **Management**, and **Directorate**.

**The Mapping:**

| Group       | Associated Role |
| :---------- | :-------------- |
| Directorate | `Director`      |
| Management  | `Manager`       |
| Analysts    | `Analyst`       |

**Scenario A: The "Super User"**
A user holding all three roles (`Director`, `Manager`, and `Analyst`) initiates a measurement.

> **Result:** The process is **immediately approved**, as the user satisfies the autonomy requirements for all three groups instantly.

**Scenario B: The Manager**
A user holds the `Manager` and `Analyst` roles, but not `Director`.

> **Result:** This user can move the process forward through the Analyst and Management stages, but the process will **halt** and wait specifically for an action from a user with the `Director` role.

***

## Organizations & Permissions

At the highest level, all Roles and Groups exist within an **Organization (Org)**. The Org represents the company or client using H3aven.

### Permission Levels

When assigning Roles or configuring Policies, permissions define the scope of access:

| Permission | Description                                                                 |
| :--------- | :-------------------------------------------------------------------------- |
| **NONE**   | The user has the Role but no practical access to data or actions.           |
| **VIEW**   | Read-only access. The user can view data and variables but cannot edit.     |
| **EDIT**   | Full access. The user can read data and write/execute actions on contracts. |

<Note>
  **Org Administration:** When an Organization is created, the creator is automatically assigned the `ORG_ADMIN_ROLE`. This user is responsible for inviting colleagues and assigning their respective Roles.
</Note>

## Setting Up Groups

Follow these steps to configure a new flow:

<Steps>
  <Step title="Access Process Settings">
    Navigate to the process you wish to configure and open the **Approval** tab.
  </Step>

  <Step title="Define Groups">
    Create the necessary groups (e.g., "Financial Approval", "Technical Review").
  </Step>

  <Step title="Assign Roles">
    Map the specific user Roles (e.g., `finance_analyst@company.com`) to the created Groups.
  </Step>

  <Step title="Set Order (Optional)">
    If a hierarchy is needed, define the sequence of interaction (e.g., Group A must approve before Group B).
  </Step>
</Steps>