CreateGroup

Method Details

Description: 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.

Required Roles: Check proto file for roles

Parameters:

• Group (message) (required): The group configuration for creation. The name field will be ignored and assigned by the system.

Returns: Group

Method Type: METHOD_TYPE_WRITE

Code Examples

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();
        }
    }
}

Protobuf

syntax = "proto3";

package meshtrade.iam.group.v1;

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

option go_package = "github.com/meshtrade/api/go/iam/group/v1;groupv1";
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.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      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) = {
    string: {
      min_len: 1
      pattern: "^groups/[0-9A-Z]{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/[0-9A-Z]{26}$')"
    }
  }];
}

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