Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing access Grey arrow pointing right RBAC API Grey arrow pointing right RBAC API v1 Grey arrow pointing right User group endpoints Grey arrow pointing right

User group endpoints

Sections

ExpandCollapse

Groups are used to assign roles to a group of users, which is vastly more efficient than managing roles for each user individually. The groups endpoints enable you to get lists of groups and to add a new directory group.

Remember: Group membership is determined by the directory service hierarchy and, as such, local users cannot be in directory groups.

User group keys

These keys are used with the RBAC v1 API's groups endpoints.

Key Explanation Example
id A UUID string identifying the group. "c099d420-5557-11e4-916c-0800200c9a66"
login The identifier for the user group on the directory server. "poets"
display_name The group's name as a string. "Poets"
role_ids An array of role IDs indicating roles to be inherited by the group's members. An empty array is valid. This is the only field that can be updated via RBAC; the rest are immutable or synced from the directory service. [3 6 5]

is_group

is_remote

is_superuser

 These flags indicate that the group is a group. true, true, false, respectively
is_revoked Setting this flag to true currently does nothing for a group. true/false
user_ids An array of UUIDs indicating which users inherit roles from this group. ["3a96d280-54c9-11e4-916c-0800200c9a66"]

GET /groups

Fetches all groups. Supports filtering by ID through query parameters. Authentication is required.

Request format

To request all groups:
GET /groupsCopied!
To request specific groups, add a comma-separated list of group IDs:
GET /groups?id=65a068a0-588a-11e4-8ed6-0800200c9a66,75370a30-588a-11e4-8ed6-0800200c9a66Copied!
Example curl request:
curl 'https://$(puppet config print server):4433/rbac-api/v1/groups' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

The response is a JSON object that lists the metadata for all requested groups. For example:
[{
  "id": "65a068a0-588a-11e4-8ed6-0800200c9a66",
  "login": "hamsters",
  "display_name": "Hamster club",
  "role_ids": [2, 3],
  "is_group" : true,
  "is_remote" : true,
  "is_superuser" : false,
  "user_ids": ["07d9c8e0-5887-11e4-8ed6-0800200c9a66"]}
},{
  "id": "75370a30-588a-11e4-8ed6-0800200c9a66",
  "login": "chinchilla",
  "display_name": "Chinchilla club",
  "role_ids": [2, 1],
  "is_group" : true,
  "is_remote" : true,
  "is_superuser" : false,
  "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]
},{
  "id": "ccdbde50-588a-11e4-8ed6-0800200c9a66",
  "login": "wombats",
  "display_name": "Wombat club",
  "role_ids": [2, 3],
  "is_group" : true,
  "is_remote" : true,
  "is_superuser" : false,
  "user_ids": []
}]Copied!

GET /groups/<sid>

Fetches a single group by its subject ID (<sid>). Authentication is required.

Request format

Example curl request:
curl 'https://$(puppet config print server):4433/rbac-api/v1/groups/65a068a0-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

The response contains an ID for the group and a list of role_ids the group is directly assigned to.

For directory groups, the response contains the display name, the login field, a list of role_ids directly assigned to the group, and user_ids containing IDs of the remote users that belong to that group.

For example:
{"id": "65a068a0-588a-11e4-8ed6-0800200c9a66",
"login": "hamsters",
"display_name": "Hamster club",
"role_ids": [2, 3],
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["07d9c8e0-5887-11e4-8ed6-0800200c9a66"]}Copied!

Error responses

If the user who submits the GET request has not successfully authenticated, the endpoint returns 401 Unauthorized.

If the current user does not have the appropriate user permissions to request the group data, the endpoint returns 403 Forbidden.

POST /groups

Creates a new remote group and attaches to the new group any roles specified in its roles list. Authentication is required.

Request format

Accepts a JSON body containing an entry for login and an array of role_ids to assign to the group initially. For example:
{"login":"Augmentators",
"role_ids": [1,2,3]}Copied!
Example curl request:
curl POST 'https://$(puppet config print server):4433/rbac-api/v1/groups' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"login":"Augmentators",
     "role_ids": [1,2,3]}Copied!

Response format

If the create operation is successful, the endpoint returns 201 Created with a location header that points to the new resource.

Error responses

If the login for the group conflicts with an existing group login, the endpoint returns 409 Conflict.

PUT /groups/<sid>

Replaces the group with the specified ID (<sid>) with a new group object. Authentication is required.

Request format

Accepts an updated group object containing all the keys that were received from the API initially. The only field you can update is role_ids. An empty role_ids array indicates a desire to remove the group from all the roles it was directly assigned to. Any other changed values are ignored.

For example:
{"id": "75370a30-588a-11e4-8ed6-0800200c9a66",
"login": "chinchilla",
"display_name": "Chinchillas",
**"role_ids": [2, 1],**
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}Copied!
Example curl request:
curl -X PUT 'https://$(puppet config print server):4433/rbac-api/v1/groups/75370a30-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"id":"75370a30-588a-11e4-8ed6-0800200c9a66",
     "login":"chinchilla",
     "display_name":"Chinchillas",
     "role_ids":[2,1],
     "is_group":true,
     "is_remote":true,
     "is_superuser":false,
     "user_ids":["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'Copied!

Response format

If the operation is successful, the endpoint returns 200 OK and a group object with updated roles.

DELETE /groups/<sid>

Deletes the user group with the specified ID (<sid>) from RBAC without making any changes to the directory service. Authentication required.

Request format

Example curl request:
curl -X DELETE 'https://$(puppet config print server):4433/rbac-api/v1/groups/75370a30-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

If the user group is successfully deleted, the endpoint returns 204 No Content.

Error responses

If the current user does not have the user_groups:delete permission for this user group, the endpoint returns 403 Forbidden.

If a group with the provided identifier does not exist, the endpoint returns 404 Not Found.