--- title: Groups description: The Groups service enables you to create collections of users having 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. component: pingone-api page_id: pingone-api:platform:groups canonical_url: https://developer.pingidentity.com/pingone-api/platform/groups.html section_ids: groups-groups-permissions: Groups permissions groups-creating-groups: Creating groups groups-nesting-groups: Nesting groups groups-circular-references: Creating circular references groups-removing-nested-relationship: Removing nested relationship groups-searching-for-group-membership: Searching for group membership groups-filtering-groups-searches: Filtering groups searches assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service groups-data-model: Groups data model group-events-generated: Group events generated groups-response-codes: Groups response codes --- # Groups The Groups service enables you to create collections of users having 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 using the PingOne APIs: * Create, read, update, and delete groups * Add users to groups * Delete users from groups * Read group memberships If you have the Environment Admin or Client Application Developer role, you can read groups. ## Creating groups Use [POST {{apiPath}}/environments/{{envID}}/groups](groups/create-group.html) 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 {{apiPath}}/environments/{{envID}}/groups](groups/create-group.html). The `population.id` property is read-only after it is initially set and can be set in [POST {{apiPath}}/environments/{{envID}}/groups](groups/create-group.html) only. Once a group is created, the following conditions apply: You cannot move the group: * From one population to another * From a population to an environment * From an environment to a population | | | | - | ------------------------------------------------------------------------------------------------------------ | | | If a user's population changes, they are also removed from any group that contains them for this population. | Learn more about creating groups in [Creating a group](https://docs.pingidentity.com/pingone/directory/p1_create_group.html), in the PingOne Admin Guide. Learn more about assigning users to groups in [Group Membership](users/group-membership.html). ## Nesting groups You can nest one group inside another. The members of the nested group dynamically become members of the parent group. Do this by specifying the ID of a group within the body of a [POST {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups](groups/create-nested-group.html) operation. Nesting a group essentially creates a child-parent relationship where members of the "child" group inherit the same properties and permissions as the "parent" group. For example, assume an environment has three groups: Group A, Group B, and Group C. Each group has access to a single application: Group A has access to App1, Group B has access to App2, and Group C has access to App3. * If you nest Group B inside of Group A, then users in Group B will now have access to App1 and App2, and Group A will still only have access to App1. * If you nest Group C into Group B, then Group C members will inherit access to App1 (via the nested relationship of Group B to Group A), inherit access to App2 (via the nested relationship of Group C to Group B), and will retain access to App3. ```none Group A - App1 Group B - App1 & App2 Group C - App1, App2, App3 [source] ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------- | | | * You cannot nest an environment-level group inside a population-level group. * You cannot nest groups with admin roles assigned. | Learn more about nested groups in [Nested groups](https://docs.pingidentity.com/pingone/directory/p1_groups_vs_populations.html#p1-nested-groups), in the PingOne Admin Guide. ### Creating circular references You can nest parent groups inside their child groups. Continuing the example from the last section, let us assume you have another group, Group D. Group D has access to App4. * If you nest Group D in Group B, Group D inherits access to Group A and Group B apps. * If you nest Group B in Group D, creating a circular reference, then both Group B and Group C inherit access to App4. ```none Group A - App1 Group B - App1 & App2, App4 Group C - App1, App2, App3, App4 Group D - App1, App2, App4 Group B - App1, App2, App4 ``` ### Removing nested relationship Use the [DELETE {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups/{{nestedGroupID}}](groups/delete-nested-group.html) operation to remove the nested relationship between two groups. Members directly assigned to each group remain unchanged. ## Searching for group membership Documentation for the following group membership searches can be found under [Users](users.html)/[Group Membership](users/group-membership.html): * [GET Read One Group Membership for User](users/group-membership/read-one-group-membership-for-user.html) * [GET Read All Group Memberships for User](users/group-membership/read-all-group-memberships-for-user.html) * [GET Read All Group Names for User](users/group-membership/read-all-group-names-for-user.html) * [GET Read All Group IDs for User](users/group-membership/read-all-group-ids-for-user.html) * [GET Read All Users in a Group](users/group-membership/read-all-users-in-a-group.html) * [GET Read All Users in Multiple Groups](users/group-membership/read-all-users-in-multiple-groups.html) * [GET Read All Users in a Group with Other Attribute](users/group-membership/read-all-users-in-a-group-with-other-user-attribute.html) Learn more about searching for groups in [Searching for groups](https://docs.pingidentity.com/pingone/directory/p1_searching_groups.html), in the PingOne Admin Guide. ### 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 operators `eq` (equals), `sw` (starts with), `and`, and `or` can be used with the following group properties: * `name` * `externalId` The SCIM operators `eq` (equals), and `sw` (starts with) can be used with the group property: * `displayName` The SCIM operator `eq` (equals) can be used with the following group properties: * `id` * `population.id` * `sourceId` (only for external groups) For more information refer to [Paging and ordering collections](reference/paging-ordering-collections.html). You can also use SCIM filters with GET collection requests that return user data. Refer to [Users](users.html) for the user properties and operators supported. ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.html) for more information. ## Groups data model | Property | Type | Required? | Mutable? | Description | | -------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `customData` | JSON blob | Optional | Mutable | User-defined custom data. | | `description` | String | Optional | Mutable | The group description. | | `displayName` | String | Optional | Mutable | For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with `memberOfExternalGroups[].name`. Refer to the [Users data model](users/users-1.html#users-data-model) for more information. For internal groups it is identical to `name`. Groups can be filtered by `displayName`. | | `directMemberCounts` | Object | Optional | Immutable | An object containing a `users` (int) property. This property lists the number of users explicitly added to the group with [POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups](users/group-membership/add-user-to-group.html). Since these members were explicitly added to the group, they can be removed from the group with [DELETE {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}}](users/group-membership/remove-user-from-group.html). | | `environment.id` | String | Required | Immutable | The unique identifier for the environment. | | `externalId` | String | Optional | Mutable | A user-defined identifier for the group. Use this property to synchronize 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 using [GET {{apiPath}}/environments/{{envID}}/groups](groups/read-all-groups.html). | | `id` | String | Required | Immutable | The unique identifier for the group. Search all groups for a specific group ID with a SCIM filter on [GET {{apiPath}}/environments/{{envID}}/groups](groups/read-all-groups.html). Retrieve all the group IDs associated with a user with [GET {{apiPath}}/environments/{{envID}}/users/{{userID}}?include=memberOfGroupIDs](users/group-membership/read-all-group-ids-for-user.html). | | `isAdmin` | Boolean | N/A | Read-only | `true` indicates that admin role assignments are present for this group. | | `name` | String | Required | Immutable | 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 {{apiPath}}/environments/{{envID}}/groups](groups/read-all-groups.html). Retrieve all the group names associated with a user with [GET {{apiPath}}/environments/{{envID}}/users/{{userID}}?include=memberOfGroupNames](users/group-membership/read-all-group-names-for-user.html). Use this operation to determine group membership in attribute mappings for claims and assertions. | | `population.id` | String | Optional | Immutable | The unique identifier for the population. Set this property during group creation only. If set, membership to the group is restricted to a single population. For more information, refer to [Creating groups](#groups-creating-groups). Search all groups for a specific population ID with a SCIM filter on [GET {{apiPath}}/environments/{{envID}}/groups](groups/read-all-groups.html). | | `sourceId` | String | Optional | Immutable | For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with `memberOfExternalGroups[].sourceId`. Refer to the [Users data model](users/users-1.html#users-data-model) for more information. Groups that are provisioned set this property when the groups are created. Groups can be filtered by `sourceId`. | | `sourceType` | String | Optional | Immutable | For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with `memberOfExternalGroups[].sourceType`. Currently, this can be only "GATEWAY" or "IDP". Refer to the [Users data model](users/users-1.html#users-data-model) for more information. | | `totalMemberCounts` | Object | Optional | Immutable | An object containing a `users` (int) property. This property lists the total number of users added to the group. You must use [GET {{apiPath}}/environments/{{envID}}/groups/{{groupID}}](groups/read-one-group.html) with the `include=totalMemberCounts` query parameter to retrieve this property. This property is not returned with a list of groups. | | `type` | String | Optional | Immutable | Defines the relationship of nested group membership: `DIRECT` or `INDIRECT`. | | `userFilter` | String | Optional | Mutable | A SCIM filter that determines which users are dynamically added to the group. Can only be used to add members of non-admin groups. For more information, refer to [Group Membership](users/group-membership.html). | ## Group events generated Refer to [Audit Reporting Events](reference/audit-reporting-events.html) for the events generated. ## 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. | > **Collapse: Related topics** > > * [Control access to applications through roles and groups](../foundations/pingone-roles-scopes-and-permissions/control-access-to-applications-through-roles-and-groups.html)