The Groups service enables you to create collections of users with the same access to applications. You can create up to 100,000 groups per environment. There is no limit to the number of users that can belong to a group.

Groups Permissions

If you have the Identity Data Admin role, you can perform the following operations:

If you have the Environment Admin or Client Application Developer role, you can read groups.

Creating groups

Use POST /environments/{envID}/groups to create a new group.

By default, groups are created per environment. Groups can also optionally be created per population. Do this by specifying a value for population.id in the body of POST /environments/{envID}/groups. The population.id property is read-only after it is initially set and can be set in POST /environments/{envID}/groups only.

Adding users to a group

There are two ways to add users to a group. The first is to directly add them with the POST /environments/{envID}/users/{userID}/memberOfGroups operation. These members are included in both the directUserCounts and totalUserCounts properties.

The second method is to dynamically add users to a group with the userFilter filter property. You can use this filter with the POST /environments/{envID}/groups and PUT /environments/{envID}/groups/{groupID} operations. Place the filter in the body of the request as shown in the example below:

{
    ...
    "userFilter": "title eq \'Manager\'",
    ...
}

When the POST or PUT operations above are executed, all existing users that meet the filter criteria are dynamically added to the group. In addition, all subsequent new users that are added that meet the filter criteria are also added to the group. The filter supports all the operators and properties that are supported when searching user data. See Users for a complete list. Members added in this way are included in the totalUserCounts property, but not the directUserCounts property.

Removing users from a group

Members directly added to a group with the POST /environments/{envID}/users/{userID}/memberOfGroups operation are removed from the group with the DELETE /environments/{envID}/users/{userID}/memberOfGroups/{groupID} operation.

Members dynamically added to a group with the userFilter filter property are automatically removed from the group when the filter criteria is no longer met. You can do this by changing the filter criteria with PUT /environments/{envID}/groups/{groupID} or by changing the user data to no longer match the filter criteria. You cannot remove these members with the DELETE /environments/{envID}/users/{userID}/memberOfGroups/{groupID} operation.

Searching for group membership.

Documentation for the following group membership searches can be found under Users/Group Membership:

Filtering groups searches

You can filter groups GET collection responses by applying a SCIM filtering expression to the request URL. For large collections, a filter expression appended to the query returns a targeted, more useful data set.

The SCIM opeators eq (equals), sw (starts with), and, and or can be used with the following group properties:

The SCIM operator eq (equals) can be used with the following group properties:

You can also use SCIM filters with GET collection requests that return user data. See Users for the user properties and operators supported.

Groups properties

Property Description
id (string) Read-only The unique identifier for the group. Search all groups for a specific group ID with a SCIM filter on GET /environments/{envID}/groups. Retrieve all the group IDs associated with a user with GET /environments/{envID}/users/{userID}?include=memberOfGroupIDs.
environment.id (string) Read-only The unique identifier for the environment.
population.id (string) Read-only after group creation The unique identifier for the population. Set this optional property during group creation only. If set, membership to the group is restricted to a single population. For more information, see Creating groups. Search all groups for a specific population ID with a SCIM filter on GET /environments/{envID}/groups.
name (string) Required The group name. A group name can be reused across populations, but the same user cannot belong to multiple groups with the same group name. Population groups cannot share a group name with an environment group. Search all groups for a specific group name with a SCIM filter on GET /environments/{envID}/groups. Retrieve all the group names associated with a user with GET /environments/{envID}/users/{userID}?include=memberOfGroupNames. Use this operation to determine group membership in attribute mappings for claims and assertions.
userFilter (string) Optional A SCIM filter that determines which users are dynamically added to the group. For more information, see Adding users to a group and Removing users from a group.
description (string) Optional The group description.
externalId (string) Optional A user-defined identifier for the group. Use this propertry to syncronize a group in PingOne with the same group in an external system. PingOne does not directly use this property. Search all groups for a specific external ID with a SCIM filter on GET /environments/{envID}/groups
customData (JSON blob) Optional User-defined custom data.
directMemberCounts (object) Read-only An object containing a users (int) property. This property lists the number of users explicitly added to the group with POST /environments/{envID}/users/{userID}/memberOfGroups. Since these members were explicitly added to the group, they can be removed from the group with DELETE /environments/{envID}/users/{userID}/memberOfGroups/{groupID}.
totalMemberCounts (object) Read-only An object containing a users (int) property. This property lists the total number of users added to the group. You must use GET /environments/{envID}/groups with the include=totalMemberCounts query parameter to retrieve this property. This property is not returned with a list of groups.

Groups response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.