ListGroups

Method Details

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

Required Roles: Check proto file for roles

Parameters:

• Sorting (message) (required): Optional sorting configuration.

Returns: ListGroupsResponse

Method Type: METHOD_TYPE_READ

Code Examples

Go

package main

import (
	"context"
	"log"

	groupv1 "github.com/meshtrade/api/go/iam/group/v1"
	typev1 "github.com/meshtrade/api/go/type/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()

	// Create request with optional sorting
	request := &groupv1.ListGroupsRequest{
		Sorting: &groupv1.ListGroupsRequest_Sorting{
			Field: "display_name", // Sort by human-readable name
			Order: typev1.SortingOrder_SORTING_ORDER_ASC,
		},
	}

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

	// Process the complete organizational hierarchy
	log.Printf("Found %d groups in the accessible hierarchy:", len(response.Groups))
	for i, group := range response.Groups {
		log.Printf("Group %d:", i+1)
		log.Printf("  Name: %s", group.Name)
		log.Printf("  Display Name: %s", group.DisplayName)
		log.Printf("  Owner: %s", group.Owner)
		log.Printf("  Hierarchy Depth: %d levels", len(group.Owners))
		if group.Description != "" {
			log.Printf("  Description: %s", group.Description)
		}
		log.Println()
	}
	
	// Use groups for resource ownership and access control
	log.Printf("All groups are available for owning resources and managing access")
}

Python

from meshtrade.iam.group.v1 import (
    GroupService,
    ListGroupsRequest,
)
from meshtrade.type.v1 import SortingOrder


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:
        # Create request with optional sorting
        request = ListGroupsRequest(
            sorting=ListGroupsRequest.Sorting(
                field="display_name",  # Sort by human-readable name
                order=SortingOrder.SORTING_ORDER_ASC,
            )
        )

        # Call the ListGroups method
        response = service.list_groups(request)

        # Process the complete organizational hierarchy
        print(f"Found {len(response.groups)} groups in the accessible hierarchy:")
        for i, group in enumerate(response.groups, 1):
            print(f"Group {i}:")
            print(f"  Name: {group.name}")
            print(f"  Display Name: {group.display_name}")
            print(f"  Owner: {group.owner}")
            print(f"  Hierarchy Depth: {len(group.owners)} levels")
            if group.description:
                print(f"  Description: {group.description}")
            print()

        # Use groups for resource ownership and access control
        print("All groups are available for owning resources and managing access")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.group.v1.GroupService;
import co.meshtrade.api.iam.group.v1.Service.ListGroupsRequest;
import co.meshtrade.api.iam.group.v1.Service.ListGroupsResponse;
import co.meshtrade.api.iam.group.v1.Group.Group;
import co.meshtrade.api.type.v1.Sorting.SortingOrder;

import java.util.Optional;

public class ListGroupsExample {
    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()) {
            // Create request with optional sorting
            ListGroupsRequest request = ListGroupsRequest.newBuilder()
                .setSorting(ListGroupsRequest.Sorting.newBuilder()
                    .setField("display_name")  // Sort by human-readable name
                    .setOrder(SortingOrder.SORTING_ORDER_ASC)
                    .build())
                .build();

            // Call the ListGroups method
            ListGroupsResponse response = service.listGroups(request, Optional.empty());

            // Process the complete organizational hierarchy
            System.out.println("Found " + response.getGroupsCount() + " groups in the accessible hierarchy:");
            for (int i = 0; i < response.getGroupsCount(); i++) {
                Group group = response.getGroups(i);
                System.out.println("Group " + (i + 1) + ":");
                System.out.println("  Name: " + group.getName());
                System.out.println("  Display Name: " + group.getDisplayName());
                System.out.println("  Owner: " + group.getOwner());
                System.out.println("  Hierarchy Depth: " + group.getOwnersCount() + " levels");
                if (!group.getDescription().isEmpty()) {
                    System.out.println("  Description: " + group.getDescription());
                }
                System.out.println();
            }
            
            // Use groups for resource ownership and access control
            System.out.println("All groups are available for owning resources and managing access");
        } catch (Exception e) {
            System.err.println("ListGroups 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