CreateGroup

Creates a new child group within the authenticated group's hierarchy.

The new group inherits access from its parent and becomes part of the organizational structure. Group ownership must match the executing context.

Overview

Method Options

Authorisation specification of the CreateGroup method.

Type	METHOD_TYPE_WRITE
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_IAM_ADMIN ROLE_IAM_GROUP_ADMIN

Parameters

Request and response parameter message overview:

Input: CreateGroupRequest Message

Field	Type	Required	Description
Group	meshtrade.iam.group.v1.Group	True	The group configuration for creation. The name field will be ignored and assigned by the system.

Returns: Group Message

Protobuf

syntax = "proto3";

package meshtrade.iam.group.v1;

import "buf/validate/validate.proto";
import "meshtrade/iam/group/v1/group.proto";
import "meshtrade/option/method_options/v1/method_options.proto";
import "meshtrade/type/v1/sorting.proto";

option go_package = "github.com/meshtrade/api/go/iam/group/v1;group_v1";
option java_package = "co.meshtrade.api.iam.group.v1";

/*
   GroupService manages organizational group hierarchy and lifecycle operations.

   Groups are the fundamental multi-tenancy units in Mesh that own resources,
   define permission boundaries, and enable hierarchical access control.
   Each group can own sub-groups, users, API users, and platform resources,
   forming tree structures for inherited permissions and resource isolation.

   All operations are scoped to the authenticated group's hierarchy and
   require appropriate IAM domain permissions.
*/
service GroupService {
  /*
     Creates a new child group within the authenticated group's hierarchy.

     The new group inherits access from its parent and becomes part of the
     organizational structure. Group ownership must match the executing context.
  */
  rpc CreateGroup(CreateGroupRequest) returns (Group) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_GROUP_ADMIN
      ]
    };
  }

  /*
     Updates an existing group's display name and description metadata.

     Only mutable fields can be modified while preserving the group's
     identity and ownership within the hierarchy.
  */
  rpc UpdateGroup(UpdateGroupRequest) returns (Group) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_GROUP_ADMIN
      ]
    };
  }

  /*
     Retrieves all groups within the authenticated group's hierarchical scope.

     Returns the complete organizational structure accessible to the executing
     context, including the root group and all descendant groups.
  */
  rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }

  /*
     Searches groups using flexible text criteria within the hierarchy.

     Performs case-insensitive substring matching on display names and
     descriptions using OR logic across search terms.
  */
  rpc SearchGroups(SearchGroupsRequest) returns (SearchGroupsResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }

  /*
     Retrieves a specific group by its resource identifier within the hierarchy.

     Provides access to a single group's complete metadata and organizational
     context if accessible within the executing group's scope.
  */
  rpc GetGroup(GetGroupRequest) returns (Group) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_GROUP_ADMIN,
        ROLE_IAM_GROUP_VIEWER
      ]
    };
  }
}

/*
   Request to create a new group.
*/
message CreateGroupRequest {
  /*
     The group configuration for creation.
     The name field will be ignored and assigned by the system.
  */
  Group group = 1 [(buf.validate.field) = {required: true}];
}

/*
   Request to update an existing group.
*/
message UpdateGroupRequest {
  /*
     Complete group resource with updated fields.
     Only display_name and description can be modified.
  */
  Group group = 1 [(buf.validate.field) = {required: true}];
}

/*
   Request to list all groups in the hierarchy.
*/
message ListGroupsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by (e.g., "name", "display_name").
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "name",
          "display_name"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: name, display_name, or empty"
        expression: "this in ['', 'name', 'display_name']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;
}

/*
   Response containing a list of groups.
*/
message ListGroupsResponse {
  /*
     Collection of groups in the hierarchy.
  */
  repeated Group groups = 1;
}

/*
   Request to search groups with filtering criteria.
*/
message SearchGroupsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by ("name" or "display_name").
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "name",
          "display_name"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: name, display_name, or empty"
        expression: "this in ['', 'name', 'display_name']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional substring to search for in group display names.
     Case-insensitive partial matching.
  */
  string display_name = 1 [(buf.validate.field) = {
    string: {max_len: 255}
    cel: {
      id: "display_name.max_length"
      message: "display_name search term must not exceed 255 characters"
      expression: "size(this) <= 255"
    }
  }];

  /*
     Optional substring to search for in group descriptions.
     Case-insensitive partial matching.
  */
  string description = 2 [(buf.validate.field) = {
    string: {max_len: 255}
    cel: {
      id: "description.max_length"
      message: "description search term must not exceed 255 characters"
      expression: "size(this) <= 255"
    }
  }];

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 3;
}

/*
   Response containing search results.
*/
message SearchGroupsResponse {
  /*
     Collection of groups matching the search criteria.
  */
  repeated Group groups = 1;
}

/*
   Request to retrieve a specific group.
*/
message GetGroupRequest {
  /*
     The resource name of the group to retrieve in format groups/{group_id}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      min_len: 1
      pattern: "^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format groups/{ULIDv2}"
      expression: "size(this) > 0"
    }
    cel: {
      id: "name.format"
      message: "name must be in format groups/{ULIDv2} where ulidv2 is exactly 26 uppercase alphanumeric characters"
      expression: "this.matches('^groups/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
    }
  }];
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"log"

	groupv1 "github.com/meshtrade/api/go/iam/group/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := groupv1.NewGroupService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Get current executing group to use as owner for the new child group
	// Note: Owner format is "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
	// but you can only create groups owned by your authenticated context

	// Create request with group configuration
	request := &groupv1.CreateGroupRequest{
		Group: &groupv1.Group{
			Owner:       service.Group(), // Current executing group becomes the parent
			DisplayName: "Trading Team Alpha",
			Description: "Primary trading team for equity markets and derivatives",
		},
	}

	// Call the CreateGroup method
	group, err := service.CreateGroup(ctx, request)
	if err != nil {
		log.Fatalf("CreateGroup failed: %v", err)
	}

	// Use the newly created group
	log.Printf("Group created successfully:")
	log.Printf("  Name: %s", group.Name)
	log.Printf("  Display Name: %s", group.DisplayName)
	log.Printf("  Owner: %s", group.Owner)
	log.Printf("  Description: %s", group.Description)

	// The group can now be used to own resources and manage users
	log.Printf("Group is ready to own API users, accounts, and trading resources")
}

Python

from meshtrade.iam.group.v1 import (
    CreateGroupRequest,
    Group,
    GroupService,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = GroupService()

    with service:
        # Get current executing group to use as owner for the new child group
        # Note: Owner format is "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
        # but you can only create groups owned by your authenticated context

        # Create request with group configuration
        request = CreateGroupRequest(
            group=Group(
                owner=service.group(),  # Current executing group becomes the parent
                display_name="Trading Team Alpha",
                description="Primary trading team for equity markets and derivatives",
            )
        )

        # Call the CreateGroup method
        group = service.create_group(request)

        # Use the newly created group
        print("Group created successfully:")
        print(f"  Name: {group.name}")
        print(f"  Display Name: {group.display_name}")
        print(f"  Owner: {group.owner}")
        print(f"  Description: {group.description}")

        # The group can now be used to own resources and manage users
        print("Group is ready to own API users, accounts, and trading resources")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.group.v1.GroupService;
import co.meshtrade.api.iam.group.v1.Service.CreateGroupRequest;
import co.meshtrade.api.iam.group.v1.Group.Group;

import java.util.Optional;

public class CreateGroupExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (GroupService service = new GroupService()) {
            // Get current executing group to use as owner for the new child group
            // Note: Owner format is "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
            // but you can only create groups owned by your authenticated context

            // Create request with group configuration
            CreateGroupRequest request = CreateGroupRequest.newBuilder()
                .setGroup(Group.newBuilder()
                    .setOwner(service.group())  // Current executing group becomes the parent
                    .setDisplayName("Trading Team Alpha")
                    .setDescription("Primary trading team for equity markets and derivatives")
                    .build())
                .build();

            // Call the CreateGroup method
            Group group = service.createGroup(request, Optional.empty());

            // Use the newly created group
            System.out.println("Group created successfully:");
            System.out.println("  Name: " + group.getName());
            System.out.println("  Display Name: " + group.getDisplayName());
            System.out.println("  Owner: " + group.getOwner());
            System.out.println("  Description: " + group.getDescription());
            
            // The group can now be used to own resources and manage users
            System.out.println("Group is ready to own API users, accounts, and trading resources");
        } catch (Exception e) {
            System.err.println("CreateGroup failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Iam Group v1 Method List - For Other methods