Skip to main content

Iam Group v1 Service

Skip The Details?​

Overview​

The GroupService provides comprehensive management of organizational hierarchies within Mesh. Groups serve as the fundamental multi-tenancy units that:

  • Own Resources: Groups can own sub-groups, users, API users, accounts, and trading resources
  • Define Boundaries: Each group creates isolated tenancy boundaries for resource access
  • Enable Inheritance: Hierarchical structures allow permission and access inheritance from parent to child groups
  • Support Organization: Groups model real-world organizational structures and business units

The service provides five core operations for complete lifecycle management:

  • CreateGroup: Establish new child groups within the hierarchy
  • UpdateGroup: Modify group metadata while preserving identity
  • ListGroups: Retrieve all accessible groups in the organizational structure
  • SearchGroups: Find groups using flexible text-based criteria
  • GetGroup: Access individual group details by resource identifier

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

note

👉 See Role Based Access for more information about how roles grant permission to access resource services.

Group Hierarchy Model​

Groups form tree structures with sophisticated ownership patterns:

Ownership Structure​

  • Direct Owner: Each group has one immediate parent (stored in the owner field)
  • Full Hierarchy: Complete ownership chain maintained automatically (stored in the owners array)
  • Access Inheritance: Child groups inherit access permissions from their ancestry

Resource Isolation​

  • Tenant Boundaries: Groups provide complete isolation between organizational units
  • Scoped Operations: All operations are scoped to the authenticated group's accessible hierarchy
  • Permission Inheritance: Users and API users inherit access based on their group membership
  • Resource Ownership: All platform resources (accounts, trades, instruments) are owned by specific groups

Quick Start​

  1. Configure your client with appropriate IAM credentials and group context
  2. Identify your hierarchy scope - WRITE operations are limited to your authenticated group's tree
  3. Choose operations based on your role (admin roles for read & write operations, viewer roles for read operations)
  4. Review group structure using ListGroups to understand your organizational context

Common Workflows​

Create Organizational Sub-Units​

Use CreateGroup to establish new organizational boundaries within your hierarchy:

  • New groups become children of the authenticated group context
  • System generates unique identifiers and establishes ownership relationships
  • Group inherits access patterns from parent while creating new isolation boundaries
  • Metadata fields (display_name, description) provide human-readable identification

Maintain Group Metadata​

Use UpdateGroup to modify group information while preserving identity:

  • Only display_name and description fields can be modified
  • Group identity (name) and ownership (owner) remain immutable
  • Changes maintain consistency across the organizational hierarchy
  • Updates preserve all existing resource ownership and access patterns

Use ListGroups to understand the complete accessible hierarchy:

  • Returns authenticated group plus all descendant groups
  • Provides complete organizational context for resource ownership
  • Supports sorting for organized presentation
  • Includes full ownership chain information for each group

Locate Specific Groups​

Use SearchGroups to find groups using flexible criteria:

  • Case-insensitive substring matching on display names and descriptions
  • OR logic combines multiple search terms for broader results
  • Maintains hierarchical scoping - only searches accessible groups
  • Supports sorting to organize results meaningfully

Data Consistency​

The group service maintains several consistency guarantees:

Identity Consistency​

  • Immutable Names: Group resource names never change once assigned
  • Stable Ownership: Parent-child relationships are permanent once established
  • Unique Identifiers: System-generated ULIDv2 identifiers ensure global uniqueness

Hierarchy Consistency​

  • Ownership Validation: All operations validate group ownership against executing context
  • Access Scoping: Read operations automatically filter to accessible hierarchy scope
  • Permission Alignment: Write operations require ownership alignment with executing context

Authentication & Authorization​

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

Write Operations (CreateGroup, UpdateGroup)​

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

Read Operations (ListGroups, SearchGroups, GetGroup)​

  • Required Roles: ROLE_IAM_ADMIN, ROLE_IAM_VIEWER, ROLE_IAM_GROUP_ADMIN, or ROLE_IAM_GROUP_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 the hierarchical access patterns established by the organization's group structure.

Last updated on by Bernard Bussy