ListGroups

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.

Overview

Method Options

Authorisation specification of the ListGroups method.

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

Parameters

Request and response parameter message overview:

Input: ListGroupsRequest Message

Field	Type	Required	Description
Sorting	Field Type Required Description Field string False Field to sort by (e.g., "name", "display_name"). Order meshtrade.type.v1.SortingOrder False Sort order for results.	False	Optional sorting configuration.

Returns: ListGroupsResponse Message

Field	Type	Description
Groups	meshtrade.iam.group.v1.Group[]	Collection of groups in the hierarchy.

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"
	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)
		// System maintains hierarchical ownership relationships internally
		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();
        }
    }
}

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