Skip to main content

Client Structuring

Understanding how clients define legal entity boundaries within Mesh's hierarchical group structure and control role assignments for users and API integrations.

Overview​

Clients in Mesh serve as legal entity boundaries that define where one legal entity ends and another begins within the hierarchical group structure. Each client represents a distinct legal entity (individual, company, fund, or trust) that has undergone compliance verification and establishes the scope of role assignments for users and API users operating within that entity's organizational structure.

The Three-Layer Architecture:

  • Groups (Resource Hierarchy): Control resource ownership and access hierarchy
  • Clients (this document): Define legal entity boundaries and available role types
  • Roles (Role-Based Access Control): Control method-level API access permissions

What are Clients?​

Clients are compliance-verified legal entities that exist within the group hierarchy and define organizational boundaries for user role assignments. Each client represents a single legal entity that can operate independently and maintain its own compliance status, user base, and operational scope.

Key Characteristics:

  • Legal Entity Representation: Each client corresponds to a real-world legal entity (person, corporation, fund, trust)
  • Group Ownership: Every client is owned by exactly one group, establishing its position in the hierarchy
  • Role Boundary Definition: Clients determine which role types can be assigned to users/API users in groups under that client
  • Compliance Verification: Clients maintain verification status and audit trail for regulatory compliance
  • Multi-Tenancy: Clients provide legal entity isolation within the broader group hierarchy

Client-Group Integration​

Clients integrate seamlessly with the group ownership hierarchy to create comprehensive organizational structures where legal entities can exist at any level of the hierarchy.

Legal Entity Boundaries:

  • Broker Corporation: Legal entity at the broker level with administrative roles
  • Investment Fund: Separate legal entity with trading and reporting capabilities
  • Individual Client: Personal legal entity with limited trading permissions

Universal User System​

Both regular users and API users operate within the same client-defined role boundaries:

Regular Users: Access Mesh through web interfaces, mobile apps, desktop applications API Users: Access Mesh through programmatic API integration Unified Authorization: Both user types receive identical role assignments and follow the same client-defined role boundaries

Mesh supports four primary legal entity types, each with specific compliance and operational characteristics:

Natural Person​

Individual human beings who undergo KYC (Know Your Customer) verification.

Use Cases:

  • Individual retail traders
  • High-net-worth individuals
  • Personal investment accounts
  • Family office principals

Company​

Corporate entities including corporations, LLCs, partnerships, and other business structures.

Use Cases:

  • Trading firms and broker-dealers
  • Investment management companies
  • Corporate treasury operations
  • Business-to-business integrations

Fund​

Investment vehicles including hedge funds, mutual funds, ETFs, and other pooled investment structures.

Use Cases:

  • Hedge fund management
  • Mutual fund operations
  • ETF creation and management
  • Institutional investment vehicles

Trust​

Trust entities including family trusts, charitable trusts, and other fiduciary structures.

Use Cases:

  • Estate planning structures
  • Charitable foundations
  • Family wealth management
  • Fiduciary relationships

Hierarchy Structure Examples​

The following examples demonstrate how clients define legal entity boundaries in organizational structures of varying complexity.

Individual Client Structure​

A simple structure where an individual person operates as a single legal entity.

Key Characteristics:

  • Single Legal Entity: John Smith as a natural person
  • Group Ownership: All resources owned by John's group
  • Role Constraints: Users can only receive roles defined in client (TRADING_ADMIN, WALLET_ADMIN)
  • Unified Access: Both regular and API users operate with same permissions within the legal entity boundary

Corporate Client Structure​

A medium-complexity structure with a corporation and multiple departments.

Key Characteristics:

  • Single Legal Entity: TechCorp Inc as a company
  • Departmental Structure: Multiple groups within the corporate legal entity
  • Role Specialization: Different users receive different roles based on function
  • Hierarchical Resource Access: Corporate-level and department-level resources

Fund Management Structure​

A complex structure with multiple legal entities in a hierarchical relationship. This example demonstrates how institutional fund managers organize multiple investment vehicles, each with distinct legal entities, compliance requirements, and operational boundaries.

This diagram shows the organizational structure and legal entity relationships within the fund management structure.

Legal Structure: The management company (Goldman Asset Management) owns and operates multiple fund structures. Each legal entity undergoes independent KYC verification and maintains separate compliance obligations.

User Access & Authentication​

This diagram focuses on user access patterns, authentication methods, and role assignments across the fund structure.

Access Patterns: The system supports two types of users: human users who authenticate through SSO, credentials, or other user authentication methods, and API users who authenticate using API keys. Both user types operate within the same authorization framework but with different authentication mechanisms suitable for their usage patterns.

Financial Account Structure​

This diagram illustrates the financial account ownership and fund flow relationships within the structure.

Financial Flow: Investment capital flows from investor subscription accounts into fund master accounts, maintaining clear ownership boundaries while enabling complex fund operations.

Key Characteristics:

  • Multiple Legal Entities: Management company, two funds, and individual investor with separate legal status
  • Distinct Role Boundaries: Each client defines different available roles based on operational requirements
  • Compliance Segregation: Independent legal entities with separate verification and regulatory obligations
  • Hierarchical Legal Structure: Investment manager legally owns fund structures, funds maintain individual investor relationships
  • Segregated Financial Operations: Clear account ownership with compliant fund flow management

Client Role Assignment Architecture​

Clients control role availability through their roles field, which defines the comprehensive set of role types that can be assigned to users and API users within that client's organizational structure.

Role Definition Mechanism​

The Client protobuf includes a critical roles field that establishes role boundaries:

message Client {
  ...
  /* 
   A list of the role types that meshtrade.iam.user.v1.User and meshtrade.iam.api_user.v1.User instances may be assigned
   in groups within this client structure.

   NOTE: a viewer role at a domain e.g. IAM_VIEWER allows viewer roles in ALL sub domain roles e.g. IAM_GROUP_VIEWER
   NOTE: an admin role at a domain e.g. IAM_ADMIN allows viewer at that domain i.e. IAM_VIEWER, AND
         admin and viewer roles in ALL sub domain roles e.g., IAM_GROUP_ADMIN and IAM_GROUP_VIEWER
*/
  repeated meshtrade.iam.role.v1.Role roles = 12;
  ...
}

This field serves as the authorization boundary - users and API users in groups under this client can only be assigned roles that are explicitly listed in the client's roles array.

Role Inheritance Rules​

The system implements sophisticated role inheritance to simplify administration:

Domain-Level Roles​

Viewer Domain Inheritance:

  • Assigning ROLE_IAM_VIEWER to a client automatically allows assignment of:
    • ROLE_IAM_GROUP_VIEWER
    • ROLE_IAM_USER_VIEWER
    • ROLE_IAM_API_USER_VIEWER
    • Any other IAM sub-domain viewer roles

Admin Domain Inheritance:

  • Assigning ROLE_IAM_ADMIN to a client automatically allows assignment of:
    • ROLE_IAM_VIEWER (admin includes viewer at domain level)
    • ROLE_IAM_GROUP_ADMIN and ROLE_IAM_GROUP_VIEWER
    • ROLE_IAM_USER_ADMIN and ROLE_IAM_USER_VIEWER
    • ROLE_IAM_API_USER_ADMIN and ROLE_IAM_API_USER_VIEWER
    • All other IAM sub-domain admin and viewer roles

Role Assignment Examples​

Individual Client Role Assignment​

Corporate Client Role Assignment​

Implementation Best Practices​

Client Role Planning:

  • Principle of Least Privilege: Only assign minimum necessary roles to client
  • Domain-Level Assignment: Use domain roles (e.g., IAM_ADMIN) rather than specific sub-domain roles for flexibility
  • Future-Proofing: Consider organizational growth and role expansion needs
  • Compliance Requirements: Ensure role assignments meet regulatory separation requirements

Integration with Mesh Architecture​

Client structuring works seamlessly with Mesh's other architectural components to provide comprehensive organizational control:

Group Ownership Integration​

Clients exist within the group ownership hierarchy, with each client owned by exactly one group. The group ownership system controls resource access (READ vs WRITE permissions), while clients control role availability within that ownership structure.

Key Integration Points:

  • Client creation requires appropriate permissions in the owning group
  • Users and API users inherit resource access based on group hierarchy
  • Legal entity boundaries defined by clients respect group ownership rules

Role-Based Access Control Integration​

Client role boundaries work with the RBAC system to control method-level API access. Clients define the available role types, while RBAC determines which methods those roles can access.

Compliance and Verification​

Client verification status provides the compliance foundation for the entire organizational structure. Each client maintains independent verification status, creating clear regulatory boundaries.

Compliance Benefits:

  • Separate KYC/KYB verification for each legal entity
  • Independent compliance status and audit trails
  • Regulatory segregation between different client entities
  • Clear legal entity identification for reporting requirements

Core Architecture Components​

  • Resource Hierarchy - Understanding the hierarchical resource ownership system that provides the foundation for client positioning
  • Role-Based Access Control - Understanding the role system that clients control and how method-level permissions work

API Reference Documentation​

Implementation Guides​

  • Authentication - API key and group context authentication mechanisms that work with client role boundaries
  • Service Structure - Understanding API organization and method patterns that clients control access to