By assigning roles to users, you can manage them in sets that are granted access permissions to various PE objects. This makes tracking user access more organized and easier to manage. The roles endpoints enable you to get lists of roles and create new roles.

User role keys

The following keys are used with the RBAC v1 API’s roles endpoints.


Key	Explanation	Example
`id`	An integer identifying the role.	`18`
`display_name`	The role's name as a string.	`"Viewers"`
`description`	A string describing the role's function.	`"View-only permissions"`
`permissions`	An array containing permission objects that indicate what permissions a role grants. An empty array is valid. See Permission keys for more information.	`[]`
`user_ids` `group_ids`	An array of UUIDs indicating which users and groups are directly assigned to the role. An empty array is valid.	`["fc115750-555a-11e4-916c-0800200c9a66"]`

GET /roles

Fetches all roles with user and group ID lists and permission lists. Authentication is required.

Response format

Returns a JSON object containing all roles with user and group ID lists and permission lists.

For example:

[{"id": 123,
  "permissions": [{"object_type":"node_groups",
                   "action":"edit_rules",
                   "instance":"*"}, ...],
  "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
  "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
  "display_name": "A role",
  "description": "Edit node group rules"},
...]Copied!

GET /roles/<rid>

Fetches a single role by its ID (rid). Authentication is required.

Response format

Returns a 200 OK response with the role object with a full list of permissions and user and group IDs.

For example:

{"id": 123,
 "permissions": [{"object_type":"node_groups",
                  "action":"edit_rules",
                  "instance":"*"}, ...],
 "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
 "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
 "display_name": "A role",
 "description": "Edit node group rules"}Copied!

POST /roles

Creates a role, and attaches to it the specified permissions and the specified users and groups. Authentication is required.

Permissions keys for task-targets

If you're writing a role for a task-target, you must include unique action and instance key values to specify permissions. For the complete task-target workflow, see the blog post Puppet Enterprise RBAC API, or how to manage access to tasks.


Key	Value	Explanation
`action`	`run_with_constraints`	Specifies that the user has permission to run a task on certain nodes within the confines of a given task-target.
`instance`	`<task-target ID>`	Specifies the ID of the task-target the user has permission to run.

Request format

Accepts a new role object. Any of the arrays can be empty and "description" can be null.

For example:

{"permissions": [{"object_type":"node_groups",
                  "action":"edit_rules",
                  "instance":"*"}, ...],
 "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
 "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
 "display_name": "A role",
 "description": "Edit node group rules"}Copied!

Response format

Returns a 201 Created response with a location header pointing to the new resource.

Error responses

Returns a 409 Conflict response if the role has a name that collides with an existing role.

PUT /roles/<rid>

Replaces a role at the specified ID (rid) with a new role object. Authentication is required.

Request format

Accepts the modified role object.

For example:

{"id": 123,
 "permissions": [{"object_type":"node_groups",
                  "action":"edit_rules",
                  "instance":"*"}, ...],
 "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
 "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
 "display_name": "A role",
 "description": "Edit node group rules"}Copied!

Response format

Returns a 200 OK response with the modified role object.

Error responses

Returns a 409 Conflict response if the new role has a name that collides with an existing role.

DELETE /roles/<rid>

Deletes the role identified by the role ID (rid). Users with this role immediately lose the role and all permissions granted by it, but their session is otherwise unaffected. Access to the next request that the user makes is determined by the new set of permissions the user has without this role.

Response format

Returns a 200 OK response if the role identified by <rid> has been deleted.

Error responses

Returns a 404 Not Found response if no role exists for <rid>.

Returns a 403 Forbidden response if the current user lacks permission to delete the role identified by <rid>.

POST /command/roles/add-users

Add users to a role.

Request format

The request accepts the following keys:

Table 1.
Key	Definition
`role_id`	The ID of the role you want to add users to.
`user_ids`	A list of user IDs you want to add to the role.

Example payload:

{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}Copied!

Response format

A 204 response with no content is returned when the users are successfully added to the role.

A 404 not found response is returned if any of the users don't exist.

An error in the standard format is returned for all other responses.

POST /command/roles/remove-users

Remove users from a role.

Request format

The request accepts the following keys:

Table 2.
Key	Definition
`role_id`	The ID of the role.
`user_ids`	A list of user IDs you want to remove from the role.

Example payload:

{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}Copied!

Response format

A 204 response with no content is returned when the users are removed from the role.

Note: If a request is made with an invalid role_id, the response is still a 204 even if the users aren’t removed.

A 400 response is returned if a user doesn't exist.

An error in the standard format is returned for all other responses.

POST /command/roles/add-user-groups

Add user groups to a role.

Request format

The request accepts the following keys:

Table 3.
Key	Definition
`role_id`	The ID of the role you want to add user groups to.
`group_ids`	A list of group IDs you want to add to the role.

Example payload:

{ "role_id": <role-id>, "group_ids":[<id>,<id>,<id>] }Copied!

Response format

A 204 response with no content is returned when the user groups are successfully added to the role.

An error in the standard format is returned for all other responses.

POST /command/roles/remove-groups

Remove user groups from a role.

Request format

The request accepts the following keys:


Key	Definition
`role_id`	The ID of the role you want to remove users from.
`group_ids`	A list of group IDs you want to remove from the role.

Example payload:

{ "role_id": <role-id>, "group_ids":[1,2,3] }Copied!

Response format

A 204 response with no content is returned when the user groups are successfully removed from the role.

An error in the standard format is returned for all other responses.

POST /command/roles/add-permissions

Add permissions to a role.

Request format

The request accepts the following keys:

Table 4.
Key	Definition
`role_id`	The ID of the role you want to add permissions to.
`permissions`	A list of permissions you want to add to the role.

Example payload:

{ "role_id": <role-id>, "permissions:[{"object_type": <ot>, "action": <action>, "instance": <instance>},...]Copied!

Response format

A 204 response with no content is returned when the permissions are successfully added to the role.

An error in the standard format is returned for all other responses.

POST /command/roles/remove-permissions

Remove permissions from a role.

Request format

The request accepts the following keys:

Table 5.
Key	Definition
`role_id`	The ID of the role you want to remove permissions from.
`permissions`	A list of permissions you want to remove from the role.

Example payload:

{ "role_id": <role-id>, "permissions:[{"object_type": <ot>, "action": <action>, "instance": <instance>},...]Copied!

Response format

A 204 response with no content is returned when the permissions are successfully removed from the role.

An error in the standard format is returned for all other responses.