User group endpoints

User groups allow you to quickly assign one or more roles to a set of users by placing all relevant users in the group. This is more efficient than assigning roles to each user individually. The v2 POST /groups endpoint has additional optional parameters you can use when creating groups.

Use the v1 User groups endpoints to perform other user group functions, such as getting information about groups and deleting groups.

Remember: Group membership is determined by your directory service hierarchy. Therefore, local users (that exist only in the PE console) can't be in directory groups. You'll need to use the Users endpoints to manage these users' roles.

POST /groups

Create a new remote directory user group. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using the following keys:

login: The name to assign to the group.
role_ids: An array of role IDs defining the roles that you want to assign to users in this group. An empty array might be valid, but users can't do anything in PE if they are not assigned to any roles.

The endpoint accepts a JSON body containing these keys:


Key	Definition
`login`	Required. Defines the group for an external IdP. This could be an LDAP login or a SAML identifier for the group.
`role_ids`	Required. An array of role IDs defining the roles that you want to assign to users in this group. An empty array might be valid, but users can't do anything in PE if they are not assigned to any roles.
`display_name`	Optional. Specify a name for the group as you want it to appear in the PE console. If the group you're creating originates from an LDAP group, the LDAP group's Display name setting overrides this parameter.
`validate`	Optional. A Boolean specifying whether you want to validate if the group exists on the LDAP server prior to creating it. The default is `true`. Set this to `false` if you don't want to validate the group's existence in LDAP.

For example:

curl -X POST "https://$(puppet config print server):4433/rbac-api/v2/groups" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{
     "login": "augmentators",
     "role_ids": [1,2,3],
     "display_name: "The Augmentators"
    }'

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.

For other errors, refer to RBAC service errors.