--
:api: put-role
:request: PutRoleRequest
:response: PutRoleResponse
--
[role="xpack"]
[id="{upid}-{api}"]
=== Put Role API

[id="{upid}-{api}-request"]
==== Put Role Request

The +{request}+ class is used to create or update a role in the Native Roles
Store. The request contains a single role, which encapsulates privileges over
resources. A role can be assigned to an user using the
<<{upid}-put-role-mapping, Put Role Mapping API>>.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------

include::../execution.asciidoc[]

[id="{upid}-{api}-response"]
==== Put Role Response

The returned +{response}+ contains a single field, `created`. This field
serves as an indication if the role was created or if an existing entry was
updated.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-response]
--------------------------------------------------
<1> `created` is a boolean indicating whether the role was created or updated