Skip to main content

Groups API

See Groups and Group Policies for what a Group is and how it relates to Group Policies and roles. This page covers managing Groups themselves through the Management API.

Listing and searching groups​

curl "https://{your-id-server}/api/rest/v1/group?startIndex=0&count=50" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Supports the standard pagination, sorting, and filtering conventions.

Creating a group​

curl -X POST "https://{your-id-server}/api/rest/v1/group" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "description": "Support agents with access to the customer care tools"
  }'

Requires the GROUP_CREATE permission. name is the only required field, and must be unique within the namespace the group is created in — by default, the caller's own namespace, or specify one explicitly with nsCode.

Reading, updating, and deleting a group​

curl "https://{your-id-server}/api/rest/v1/group/{groupId}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Update with PUT (requires GROUP_MODIFY) using the same shape as creation — given fields overwrite existing values, and fields left out are reset to their defaults, not left unchanged, so include the group's current values for anything you don't want to lose. Delete with DELETE (requires GROUP_REMOVE); a group can't be deleted while it still has dependent groups nested under it.

Nesting groups​

A group can be a member of another group via memberOf, an array of the parent groups' IDs — every role and Group Policy attached to a parent group then also applies to accounts in the nested group. Set it when creating or updating a group, the same way as any other field.

To list a group's subgroups rather than its parents:

curl "https://{your-id-server}/api/rest/v1/group/{groupId}/nested" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Assigning Group Policies​

A group's userPolicies field is an array of Group Policy IDs applied to every account in the group:

curl -X PUT "https://{your-id-server}/api/rest/v1/group/{groupId}" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "userPolicies": ["{groupPolicyId}"]
  }'

Custom fields on a group​

Like user accounts, a group can hold custom field values of its own, managed through a dedicated sub-resource rather than the group object itself:

curl "https://{your-id-server}/api/rest/v1/group/{groupId}/customfields" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
Last updated on