UpdateGroup

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.

Overview

Method Options

Authorisation specification of the UpdateGroup 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: UpdateGroupRequest Message

Field	Type	Required	Description
Group	meshtrade.iam.group.v1.Group	True	Complete group resource with updated fields. Only display_name and description can be modified.

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 the existing group to update (example assumes you know the group name)
	// Note: Group names are in format "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
	// In practice, you would get this from a previous CreateGroup call or ListGroups result
	existingGroupName := "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU" // Example group name
	existingGroup, err := service.GetGroup(ctx, &groupv1.GetGroupRequest{Name: existingGroupName})
	if err != nil {
		log.Fatalf("Failed to get existing group: %v", err)
	}

	// Create request with complete group data (immutable fields must match existing)
	request := &groupv1.UpdateGroupRequest{
		Group: &groupv1.Group{
			Name:        existingGroup.Name,        // Must match existing
			Owner:       existingGroup.Owner,       // Must match existing  
			DisplayName: "Trading Team Alpha - Updated",      // Can be modified
			Description: "Primary trading team specializing in equity markets, derivatives, and fixed income instruments", // Can be modified
		},
	}

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

	// Verify the updated group information
	log.Printf("Group updated successfully:")
	log.Printf("  Name: %s (immutable)", group.Name)
	log.Printf("  Display Name: %s (updated)", group.DisplayName)
	log.Printf("  Description: %s (updated)", group.Description)
	log.Printf("  Owner: %s (immutable)", group.Owner)
	// System maintains hierarchical ownership relationships internally
	
	// Updated group retains all existing relationships and permissions
	log.Printf("Group identity preserved, metadata updated successfully")
}

Python

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


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 the existing group to update (example assumes you know the group name)
        # Note: Group names are in format "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
        # In practice, you would get this from a previous create_group call or list_groups result
        existing_group_name = "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU"  # Example group name
        existing_group = service.get_group(GetGroupRequest(name=existing_group_name))

        # Create request with complete group data (immutable fields must match existing)
        request = UpdateGroupRequest(
            group=Group(
                name=existing_group.name,  # Must match existing
                owner=existing_group.owner,  # Must match existing
                display_name="Trading Team Alpha - Updated",  # Can be modified
                description="Primary trading team specializing in equity markets, derivatives, and fixed income instruments",  # Can be modified
            )
        )

        # Call the UpdateGroup method
        group = service.update_group(request)

        # Verify the updated group information
        print("Group updated successfully:")
        print(f"  Name: {group.name} (immutable)")
        print(f"  Display Name: {group.display_name} (updated)")
        print(f"  Description: {group.description} (updated)")
        print(f"  Owner: {group.owner} (immutable)")
        print(f"  Full Ownership Path: {list(group.owners)}")

        # Updated group retains all existing relationships and permissions
        print("Group identity preserved, metadata updated successfully")


if __name__ == "__main__":
    main()

Java

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

import java.util.Optional;

public class UpdateGroupExample {
    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 the existing group to update (example assumes you know the group name)
            // Note: Group names are in format "groups/{ULIDv2}" (e.g. "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU")
            // In practice, you would get this from a previous createGroup call or listGroups result
            String existingGroupName = "groups/01HZ2XWFQ4QV2J5K8MN0PQRSTU";  // Example group name
            Group existingGroup = service.getGroup(GetGroupRequest.newBuilder()
                .setName(existingGroupName)
                .build(), Optional.empty());

            // Create request with complete group data (immutable fields must match existing)
            UpdateGroupRequest request = UpdateGroupRequest.newBuilder()
                .setGroup(Group.newBuilder()
                    .setName(existingGroup.getName())        // Must match existing
                    .setOwner(existingGroup.getOwner())       // Must match existing
                    .setDisplayName("Trading Team Alpha - Updated")  // Can be modified
                    .setDescription("Primary trading team specializing in equity markets, derivatives, and fixed income instruments")  // Can be modified
                    .build())
                .build();

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

            // Verify the updated group information
            System.out.println("Group updated successfully:");
            System.out.println("  Name: " + group.getName() + " (immutable)");
            System.out.println("  Display Name: " + group.getDisplayName() + " (updated)");
            System.out.println("  Description: " + group.getDescription() + " (updated)");
            System.out.println("  Owner: " + group.getOwner() + " (immutable)");
            System.out.println("  Full Ownership Path: " + group.getOwnersList());
            
            // Updated group retains all existing relationships and permissions
            System.out.println("Group identity preserved, metadata updated successfully");
        } catch (Exception e) {
            System.err.println("UpdateGroup 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