Skip to main content

​
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