UpdateGroup

Method Details

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

Required Roles: Check proto file for roles

Parameters:

• Group (message) (required): Complete group resource with updated fields. Only display_name and description can be modified.

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 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)
	log.Printf("  Full Ownership Path: %v", group.Owners)
	
	// 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();
        }
    }
}

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