Group Membership

For information about creating, updating, and removing groups, including nested groups and external groups, refer to Groups.

There are two ways to add users to a group. The first is to directly add them with the POST {{apiPath}}/v1/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 {{apiPath}}/v1/environments/{{envID}}/groups and PUT {{apiPath}}/v1/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. Refer to Users for a complete list. Members added in this way are included in the totalUserCounts property, but not the directUserCounts property.

A population-level group can contain users from that population only, but an environment-level group can contain users from different populations in the same environment.

You cannot delete or disable custom properties or disable standard properties in the user schema that is used by userFilter.

Learn more about managing group members in Managing group membership, in the PingOne Admin Guide.

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

If a user is a member of a group that is added to a population, changing the user’s population will remove the user from that group.

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 {{apiPath}}/v1/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 {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}} operation.

Group membership errors

In addition to the general error codes, group membership operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE`	Message: `Validation Error : [id must not be empty]` When and details When: A `POST` Add User To Group request omits the group `id` in the request body Details: `must not be empty` with target `id`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST` Add User To Group request references a group in a different population than the user, or an access request group Details: `Cannot add a user to a group in a different population` or `Cannot add a user to an access request group`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST` Add User To Group request references an external group that is not provisioned Details: `Cannot create a membership for a user within an external group` with target `memberOfGroupIDs`
400	`INVALID_DATA`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `GET` Read All Group Memberships for User request has a `limit` query parameter less than 1 or greater than 1000, or an `expand` value other than `group` Details: `must be between 1 and 1000` with target `limit`, or `<value> is not a valid expand option. Valid options: group` with target `expand`
400	`INVALID_REQUEST`	`INVALID_VALUE` or None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A request body cannot be deserialized as JSON, or a path identifier cannot be parsed as a UUID Details: For a JSON field conversion error, the detail is `Invalid value for attribute.` with target = the field path. Otherwise no detail is returned.
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST` Add User To Group request adds a membership that puts the user over the group membership limit of 10,000 direct memberships Details: `Membership count for this group has exceeded 10,000.`
401	`ACCESS_FAILED`	None	Message: `You cannot add or remove yourself from an admin group.` When and details When: A `POST` Add User To Group or `DELETE` Remove User From Group request attempts to add or remove the actor from an admin group Details: None.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `dir:create:groupMembership` permission (`POST`), the `dir:read:groupMembership` permission (`GET`), or the `dir:delete:groupMembership` permission (`DELETE`), or is not authorized for the target user’s population or the target group’s scope Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: The user ID or group ID in the request URL does not exist, or a Read One Group Membership for User request targets a user who is not a member of the group Details: None.
429	`REQUEST_LIMITED`	`LIMIT_EXCEEDED`	Message: `The request could not be completed. A rate or quota limit was reached. Please try again later.` When and details When: An update that adds group memberships puts the user over the environment’s group membership limit Details: `User is in too many groups.`

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [id must not be empty]

When and details

When: A POST Add User To Group request omits the group id in the request body

Details: must not be empty with target id

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST Add User To Group request references a group in a different population than the user, or an access request group

Details: Cannot add a user to a group in a different population or Cannot add a user to an access request group

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST Add User To Group request references an external group that is not provisioned

Details: Cannot create a membership for a user within an external group with target memberOfGroupIDs

400

INVALID_DATA

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A GET Read All Group Memberships for User request has a limit query parameter less than 1 or greater than 1000, or an expand value other than group

Details: must be between 1 and 1000 with target limit, or <value> is not a valid expand option. Valid options: group with target expand

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A request body cannot be deserialized as JSON, or a path identifier cannot be parsed as a UUID

Details: For a JSON field conversion error, the detail is Invalid value for attribute. with target = the field path. Otherwise no detail is returned.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST Add User To Group request adds a membership that puts the user over the group membership limit of 10,000 direct memberships

Details: Membership count for this group has exceeded 10,000.

401

ACCESS_FAILED

None

Message: You cannot add or remove yourself from an admin group.

When and details

When: A POST Add User To Group or DELETE Remove User From Group request attempts to add or remove the actor from an admin group

Details: None.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the dir:create:groupMembership permission (POST), the dir:read:groupMembership permission (GET), or the dir:delete:groupMembership permission (DELETE), or is not authorized for the target user’s population or the target group’s scope

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The user ID or group ID in the request URL does not exist, or a Read One Group Membership for User request targets a user who is not a member of the group

Details: None.

429

REQUEST_LIMITED

LIMIT_EXCEEDED

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

When: An update that adds group memberships puts the user over the environment’s group membership limit

Details: User is in too many groups.

PingOne Platform APIs

Group Membership

Group membership errors