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

These 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.

Request format

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/roles' \
-H "X-Authentication:$(puppet-access show)"Copied!

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 role ID (rid). Authentication is required.

Request format

Example curl request:

curl GET 'https://$(puppet config print server):4433/rbac-api/v1/roles/<rid>' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

Returns 200 OK with the role object, including a full list of permissions, user IDs, 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, refer to 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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/roles' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"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 201 Created with a location header pointing to the new resource.

Error responses

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

PUT /roles/<rid>

Replaces a role, identified by role 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!

Example curl request:

curl -X PUT 'https://$(puppet config print server):4433/rbac-api/v1/<rid> \
-H "X-Authentication: $(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{
     "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 200 OK with the modified role object.

Error responses

Returns 409 Conflict if the new role has the same name as 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.

Request format

Example curl request:

curl -X DELETE 'https://$(puppet config print server):4433/rbac-api/v1/roles/<rid>' \
-H "X-Authentication:$(puppet-access show)"Copied!

Response format

Returns 200 OK if the role identified by <rid> was deleted.

Error responses

Returns 404 Not Found if no role exists for the specified <rid>.

Returns 403 Forbidden 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 these keys:


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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-users' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "user_ids": ["5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'Copied!

Response format

Returns 204 No Content when the users are successfully added to the role.

Returns 404 Not Found 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 these keys:


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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-users' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "user_ids": ["5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'Copied!

Response format

Returns 204 No Content when the users are removed from the role.

Note: A request with an invalid role_id still returns 204 No Content even though no users were removed from the nonexistent role.

Returns 400 Bad request 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 these keys:


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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-user-groups' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"]}'Copied!

Response format

Returns 204 No Content 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 these 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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-groups' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "group_ids": ["a2450020-4217-439d-9bc4-258f6d2d7e76"]}'Copied!

Response format

Returns 204 No Content 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 these keys:


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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-permissions' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "permissions": [{"object_type":"node_groups", "action":"edit_rules", "instance":"*"}]}'Copied!

Response format

Returns 204 No Content 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 these keys:


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!

Example curl request:

curl POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-permissions' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"role_id": 1, "permissions": [{"object_type":"node_groups", "action":"edit_rules", "instance":"*"}]}'Copied!

Response format

Returns 204 No Content when the permissions are successfully removed from the role.

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