ListGroupsCommand

Suggest an Edit

Lists all groups in the identity store. Returns a paginated list of complete Group objects. Filtering for a Group by the DisplayName attribute is deprecated. Instead, use the GetGroupId API action.

If you have administrator access to a member account, you can use this API from the member account. Read about member accounts  in the Organizations User Guide.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { IdentitystoreClient, ListGroupsCommand } from "@aws-sdk/client-identitystore"; // ES Modules import
// const { IdentitystoreClient, ListGroupsCommand } = require("@aws-sdk/client-identitystore"); // CommonJS import
const client = new IdentitystoreClient(config);
const input = { // ListGroupsRequest
  IdentityStoreId: "STRING_VALUE", // required
  MaxResults: Number("int"),
  NextToken: "STRING_VALUE",
  Filters: [ // Filters
    { // Filter
      AttributePath: "STRING_VALUE", // required
      AttributeValue: "STRING_VALUE", // required
    },
  ],
};
const command = new ListGroupsCommand(input);
const response = await client.send(command);
// { // ListGroupsResponse
//   Groups: [ // Groups // required
//     { // Group
//       GroupId: "STRING_VALUE", // required
//       DisplayName: "STRING_VALUE",
//       ExternalIds: [ // ExternalIds
//         { // ExternalId
//           Issuer: "STRING_VALUE", // required
//           Id: "STRING_VALUE", // required
//         },
//       ],
//       Description: "STRING_VALUE",
//       IdentityStoreId: "STRING_VALUE", // required
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

ListGroupsCommand Input

See ListGroupsCommandInput for more details

Parameter
Type
Description
IdentityStoreId
Required
string | undefined

The globally unique identifier for the identity store, such as d-1234567890. In this example, d- is a fixed prefix, and 1234567890 is a randomly generated string that contains numbers and lower case letters. This value is generated at the time that a new identity store is created.

Filters
Filter[] | undefined

A list of Filter objects, which is used in the ListUsers and ListGroups requests.

MaxResults
number | undefined

The maximum number of results to be returned per request. This parameter is used in the ListUsers and ListGroups requests to specify how many results to return in one page. The length limit is 50 characters.

NextToken
string | undefined

The pagination token used for the ListUsers and ListGroups API operations. This value is generated by the identity store service. It is returned in the API response if the total results are more than the size of one page. This token is also returned when it is used in the API request to search for the next page.

ListGroupsCommand Output

See ListGroupsCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
Groups
Required
Group[] | undefined

A list of Group objects in the identity store.

NextToken
string | undefined

The pagination token used for the ListUsers and ListGroups API operations. This value is generated by the identity store service. It is returned in the API response if the total results are more than the size of one page. This token is also returned when it1 is used in the API request to search for the next page.

Throws

Name
Fault
Details
ResourceNotFoundException
client

Indicates that a requested resource is not found.

ValidationException
client

The request failed because it contains a syntax error.

AccessDeniedException
client

You do not have sufficient access to perform this action.

InternalServerException
server

The request processing has failed because of an unknown error, exception or failure with an internal server.

ThrottlingException
client

Indicates that the principal has crossed the throttling limits of the API operations.

IdentitystoreServiceException
Base exception class for all service exceptions from Identitystore service.