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"}

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.