> ## 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.

# Introduction

> Comprehensive user management, authentication, and role-based access control endpoints

## Overview

The Users API provides comprehensive functionality for managing users within your organization, including user lifecycle management, authentication flows, password management, and role-based access control (RBAC).

## What You Can Expect

### User Lifecycle Management

Manage the complete user journey from invitation to activation:

* **User Invitation**: Send email invitations to new users to join your platform
* **User Activation**: Handle user account activation through secure email verification links
* **Email Management**: Resend activation emails if users don't receive them initially

### Authentication & Password Management

Secure authentication endpoints for user login and password recovery:

* **Password Recovery**: Request password reset emails and complete password updates
* **Secure Token Handling**: Use single-use tokens for secure password reset flows

### User Information & Organization Management

Access and manage user data within your organization:

* **User Retrieval**: Get individual user information and details
* **Organization User Lists**: Retrieve lists of all users within your organization

### Role-Based Access Control (RBAC)

H3aven implements a sophisticated role-based access control system that combines **Roles**, **Policies**, and **Permissions** to create flexible organizational hierarchies and approval workflows.

#### Core Components

**Roles**

* Individual user identities (typically email addresses)
* Can be assigned multiple roles per user
* Same role can be assigned to multiple users
* Belong to specific organizations
* Represent job titles or functional positions

**Policies (Groups)**

* Collections of roles that share the same level of authority
* Used to configure approval flows and process permissions
* Enable redundancy (multiple people can perform the same action)
* Control access to specific system actions

**Permissions**

* Bridge entities that connect users to specific roles within organizations
* Enable the same role to be assigned to multiple users
* Scoped to organizations (a role exists within a specific org context)
* Define the organizational context for role assignments

#### Policy-Based Permissions

Policies serve as "gates" controlling access to system actions:

* **`createStep`** - Required to create and modify process steps
* **`roleGrantor`** - Required to invite users and manage permissions
* **Custom Policies** - Define business-specific access controls

#### Approval Hierarchy & Power Accumulation

The system supports sophisticated approval hierarchies where users can accumulate permissions across multiple roles:

**Example: Supplier Quotation Process**

```
Policy: "suppliers"
├── Role: "supplier-steel-abc"
├── Role: "supplier-steel-xyz"
├── Role: "supplier-steel-123"
└── Role: "supplier-steel-456"
```

This allows requesting price quotations from all steel suppliers simultaneously, rather than creating separate processes for each supplier.

**Example: Organizational Hierarchy**

```
Analyst Policy: [analyst, manager, director]
Manager Policy: [manager, director]
Director Policy: [director]
```

**Approval Scenarios:**

1. **Analyst → Manager → Director**: 3-step approval process
2. **Analyst → Director**: 2-step (director has analyst + manager power)
3. **Manager → Director**: 2-step (manager has analyst power)
4. **Director**: 1-step (director has all powers)

#### System Architecture

**Entity Relationships:**

* **User** 1 → N **Permission** (users can have multiple role assignments)
* **Permission** 1 → 1 **User** (each permission belongs to one user)
* **Permission** 1 → 1 **Organization** (permissions are scoped to orgs)
* **Organization** 1 → N **Permission** (orgs have multiple user permissions)
* **Organization** 1 → N **Policy** (orgs define available policies)
* **Policy** 1 → N **Role** (policies contain multiple roles)

**Data Models:**

**User**

* `name` (string) - Display name
* `email` (string) - Unique identifier and login
* `status` ("PENDING" | "ACTIVE") - Account state
* `permissions` (Permission\[]) - Assigned access rights

**Policy**

* `name` (string) - Policy identifier
* `roles` (string\[]) - Associated role names

**Organization**

* `name` (string) - Organization identifier
* `permissions` (Permission\[]) - All org permissions
* `policies` (Policy\[]) - Available policies

**Permission**

* `role` (string) - Role name within the organization
* `organization` (Organization) - Owning organization context
* `user` (User) - Associated user (through Permission → User relationship)

#### Practical Implementation

**Setting up a Basic Approval Flow:**

1. **Create Policies** for each approval level
2. **Assign Roles** to policies based on authority levels
3. **Create Permissions** linking users to specific roles within organizations
4. **Configure Process Steps** to use specific policies for approvals

**Example Permission Creation:**

```
User: john@company.com
Role: "manager"
Organization: "Acme Corp"
→ Creates Permission record connecting John as Manager in Acme Corp
```

**Security Best Practices:**

* Use descriptive role names that match organizational structure
* Implement least-privilege access (grant minimum required permissions)
* Regularly audit and revoke unused permissions
* Leverage policy hierarchies for scalable approval workflows

## Authentication Requirements

All Users API endpoints require proper authentication using Bearer tokens. Ensure your requests include valid authorization headers as specified in the OpenAPI specification.

## Use Cases

This API is designed to support:

* **Administrative Dashboards**: User management interfaces for organization admins
* **Self-Service Portals**: User profile management and password reset functionality
* **Automated Onboarding**: Programmatic user creation and role assignment workflows
* **Compliance Systems**: Audit trails and permission management for regulatory requirements