Listing Groups

Function

This API is used to list the IAM Identity Center groups in the specified identity source. It can be called only from the organization's management account or from a delegated administrator account of a cloud service.

URI

GET /v1/identity-stores/{identity_store_id}/groups

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
identity_store_id	Yes	String	Globally unique ID of an identity source. Minimum length: 12 Maximum length: 12

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
marker	No	String	Pagination marker. Minimum length: 24 Maximum length: 24
limit	No	Integer	Maximum number of results returned for each request. Minimum value: 1 Maximum value: 100 Default value: 100
display_name	No	String	Fuzzy query of group information by display name.

Request Parameters

**Table 3** Parameters in the request header
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	Security token (session token) of your temporary security credentials. If a temporary security credential is used, this header is required. Maximum length: 2048

Response Parameters

Status code: 200

**Table 4** Parameters in the response body
Parameter	Type	Description
groups	Array of objects	Listed groups.
page_info	Object	Pagination information.

**Table 5** groups
Parameter	Type	Description
description	String	Group description. Minimum length: 1 Maximum length: 1024
display_name	String	Display name of a group. Minimum length: 1 Maximum length: 1024
external_id	String	Identifier assigned by an external identity source to a resource.
external_ids	Array of objects	List of resource IDs issued by an external identity provider. Array length: 0-10
group_id	String	Globally unique ID of an IAM Identity Center group in the identity source. Minimum length: 1 Maximum length: 47
identity_store_id	String	Globally unique ID of an identity source. Minimum length: 1 Maximum length: 36
created_at	Long	Timestamp when a group is created.
created_by	String	Creator.
updated_at	Long	Timestamp when a group is updated.
updated_by	String	Updater

**Table 6** groups.external_ids
Parameter	Type	Description
id	String	Resource ID issued by an external identity provider. Minimum length: 1 Maximum length: 256
issuer	String	Issuer of an external ID. Minimum length: 1 Maximum length: 100

**Table 7** page_info
Parameter	Type	Description
next_marker	String	If present, it indicates that the available output is more than the output contained in the current response. Use this value in the marker request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this operation until the next_marker response returns null.
current_count	Integer	Number of records returned on this page.

Status code: 400

**Table 8** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Request ID.
encoded_authorization_message	String	Encrypted error message.

Status code: 403

**Table 9** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Request ID.
encoded_authorization_message	String	Encrypted error message.

Example Request

Listing the IAM Identity Center groups in the specified identity source

GET https://{hostname}/v1/identity-stores/{identity_store_id}/groups

Example Response

Status code: 200

Successful

{
  "groups" : [ {
    "description" : "Example group",
    "display_name" : "Group g1",
    "external_ids" : null,
    "group_id" : "0efaa0db-6aa4-7aaa-6aa5-c222aaaaf31a",
    "identity_store_id" : "d-a00aaaa33f",
    "created_at" : 1677175760379,
    "created_by" : "5146d03d8aaaaaaaaaaaabbae60620a5",
    "updated_at" : 1677175760379,
    "updated_by" : "5146d03d8aaaaaaaaaaaabbae60620a5"
  } ],
  "page_info" : {
    "next_marker" : null,
    "current_count" : 1
  }
}