User group endpoints
Sections
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"
}Copied!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.