POST /roles

Create a role. 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:

  • permissions: An array of permission objects (consisting of sets of object_type, action, and instance) defining the permissions associated with this role. Required, but can be empty. An empty array means no permissions are associated with the role.
  • group_ids: An array of group IDs defining the user groups you want to assign this role to. All users in the groups (or added to the groups in the future) receive this role through their group membership. Required, but can be empty. An empty array means the role is not assigned to any groups.
  • user_ids: An array of user IDs defining the individual users that you want to assign this role to. You do not need to repeat any users who are part of a group mentioned in group_ids. Required, but can be empty. An empty array means the role is not assigned to any individual users.
  • display_name: A string naming the role.
  • description: A string describing the role's purpose. Can be null.

For example:

curl -X 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"}'

For more information about these keys, refer to User roles endpoints keys.

If you're writing a role for a task-target, you must include unique action and instance key values to specify permissions:

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.

For the complete task-target workflow, refer to the Puppet Enterprise RBAC API, or how to manage access to tasks blog post.

Response format

If the role was successfully created, the endpoint returns a 201 Created response with a location header pointing to the new resource.

If your request included any empty arrays, you can use these endpoints to add permissions, groups, and users to your role:

Error responses

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

For other errors, refer to RBAC service errors .