Skip to main content

Iam User v1 Service

Skip The Details?​

Overview​

The UserService provides user identity management within the Mesh platform's organizational hierarchy. Users are individual identity entities that:

  • Belong to Groups: Each user is owned by a specific group within the organizational hierarchy
  • Have Unique Emails: Email addresses serve as the primary identification mechanism for users
  • Carry Role Assignments: Users can be assigned multiple roles across the group hierarchy for access control
  • Enable Authentication: Users represent authenticated entities that can access platform resources
  • Support Organization: Users model real-world individuals within organizational structures

The service provides five core operations for user lifecycle management:

  • CreateUser: Establish new users within your group context with email and initial configuration
  • GetUser: Retrieve individual user details by unique resource identifier
  • UpdateUser: Modify user information while preserving identity and ownership relationships
  • ListUsers: Enumerate all accessible users within your organizational hierarchy scope
  • SearchUsers: Locate users using email-based substring matching with flexible search criteria

Access requires IAM domain permissions with role-based access control determining operation scope and user visibility.

note

👉 See Method Permissions for more information about how roles grant permission to access resource services.

User Identity Model​

Users are identity entities with ownership and permission patterns:

Identity Structure​

  • Unique Identifier: Each user has a system-generated ULIDv2 resource name (stored in the name field)
  • Email Address: Primary identification mechanism for user discovery
  • Group Ownership: Direct ownership by a specific group (stored in the owner field)
  • Ownership Hierarchy: Complete ownership chain maintained automatically (stored in the owners array)

Permission Model​

  • Role Assignments: Users can have multiple roles assigned across different groups in the hierarchy
  • Hierarchical Access: Role assignments follow the group hierarchy for inherited permissions
  • Role-Based Operations: Different operations require different role permissions for access
  • Group-Scoped Roles: Each role assignment specifies the group context in which it applies

Email-Based Operations​

  • Unique Emails: Email addresses must be unique across the platform
  • Search Operations: Email-based substring matching for user discovery
  • Sorting Support: All list and search operations support email-based sorting
  • Validation: Email format validation enforced on all user operations

Quick Start​

  1. Configure your client with appropriate IAM credentials and group context
  2. Identify your hierarchy scope - operations are limited to your authenticated group's accessible users
  3. Choose operations based on your role (admin roles for read & write operations, viewer roles for read operations)
  4. Understand email patterns - use email-based operations for user identification and discovery

Common Workflows​

Create New Users​

Use CreateUser to add new user identities within your group context:

  • Users are created with system-generated identifiers
  • Email addresses must be unique and follow email format validation
  • Initial role assignments can be configured during creation or added later
  • System establishes ownership relationships automatically

Update User Information​

Use UpdateUser to modify user details while preserving identity:

  • Only mutable fields can be updated
  • User identity (name) and ownership relationships are preserved
  • Role modifications should use dedicated role management operations
  • Updates maintain existing access patterns

List Organization Users​

Use ListUsers to enumerate all users accessible within your hierarchy:

  • Returns users owned by your group plus users accessible through hierarchy
  • Supports email-based sorting for organized presentation
  • Includes ownership and role information for each user

Search Users by Email​

Use SearchUsers to locate users using email-based criteria:

  • Case-insensitive substring matching on email addresses
  • Maintains hierarchical scoping - only searches accessible users
  • Supports email-based sorting to organize results
  • Useful for email validation and user lookup

Get Individual User Details​

Use GetUser to access information about specific users:

  • Requires exact user resource identifier (ULIDv2-based resource name)
  • Returns user profile including ownership, roles, and hierarchy information
  • Validates access permissions against authenticated context
  • Used for user profile displays and permission validation

Authentication & Authorization​

This service implements role-based access control with hierarchical scoping:

Write Operations (CreateUser, UpdateUser)​

  • Required Roles: ROLE_IAM_ADMIN only
  • Ownership Constraint: Can only operate on users owned by the executing context
  • Method Type: METHOD_TYPE_WRITE for direct ownership validation

Read Operations (GetUser, ListUsers, SearchUsers)​

  • Required Roles: ROLE_IAM_ADMIN or ROLE_IAM_VIEWER
  • Hierarchy Scoping: Automatically limited to accessible organizational scope
  • Method Type: METHOD_TYPE_READ for extended hierarchical access

All operations operate within the authenticated group context and respect hierarchical access patterns established by the organization's group structure.