User group endpoints

You use groups to assign roles to a group of users, which is more efficient than managing roles for each user individually. Unlike the v1 POST /groups endpoint, the v2 POST /groups endpoint has an optional validate query parameter, allowing you to validate that a group exists on the LDAP server before creating it.

POST /groups

Create a new remote group and attach roles to it (specified by role IDs). Authentication is required.

Request format

The endpoint accepts a JSON body containing these keys:
Key Definition
login Defines the group for an external IdP. This could be an LDAP login or a SAML identifier for the group. Required.
role_ids An array of role IDs to assign to the group initially. Required.
display_name The name of the group that displays in the console. If this represents an LDAP group, the LDAP group display name overrides it. Optional.
validate Validate that the group exists on the LDAP server prior to creating it. Defaults to true. If false, the group is not validated against LDAP. Optional.
Example:
{
  "login": "augmentators",
  "role_ids": [1,2,3],
  "display_name: "The Augmentors"
 }

Response format

If the new remote group is created successfully, the endpoint returns 303 See Other with a location header pointing to the new resource.

Error response

Returns 409 Conflict if the new group conflicts with an existing group.