[role="xpack"]
[[security-api-put-role]]
=== Create or update roles API
++++
<titleabbrev>Create or update roles</titleabbrev>
++++

Adds and updates roles in the native realm.

[[security-api-put-role-request]]
==== {api-request-title}

`POST /_security/role/<name>` +

`PUT /_security/role/<name>`


[[security-api-put-role-prereqs]]
==== {api-prereq-title}

* To use this API, you must have at least the `manage_security` cluster
privilege.

[[security-api-put-role-desc]]
==== {api-description-title}

The role API is generally the preferred way to manage roles, rather than using
file-based role management. For more information about the native realm, see 
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 


[[security-api-put-role-path-params]]
==== {api-path-parms-title}

`name`::
  (string) The name of the role.


[[security-api-put-role-request-body]]
==== {api-request-body-title}

The following parameters can be specified in the body of a PUT or POST request
and pertain to adding a role:

`applications`:: (list) A list of application privilege entries.
`application` (required)::: (string) The name of the application to which this entry applies
`privileges`::: (list) A list of strings, where each element is the name of an application
privilege or action.
`resources`::: (list) A list resources to which the privileges are applied. 

`cluster`:: (list) A list of cluster privileges. These privileges define the
cluster level actions that users with this role are able to execute.

`global`:: (object) An object defining global privileges. A global privilege is
a form of cluster privilege that is request-aware. Support for global privileges
is currently limited to the management of application privileges.
This field is optional.

`indices`:: (list) A list of indices permissions entries.
`field_security`::: (list) The document fields that the owners of the role have
read access to. For more information, see
{stack-ov}/field-and-document-access-control.html[Setting up field and document level security].
`names` (required)::: (list) A list of indices (or index name patterns) to which the
permissions in this entry apply.
`privileges`(required)::: (list) The index level privileges that the owners of the role
have on the specified indices.
`query`::: A search query that defines the documents the owners of the role have
read access to. A document within the specified indices must match this query in
order for it to be accessible by the owners of the role.

`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
that begin with `_` are reserved for system usage.

`run_as`:: (list) A list of users that the owners of this role can impersonate.
For more information, see
{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].

For more information, see {stack-ov}/defining-roles.html[Defining roles].

[[security-api-put-role-example]]
==== {api-examples-title}

The following example adds a role called `my_admin_role`:

[source,console]
--------------------------------------------------
POST /_security/role/my_admin_role
{
  "cluster": ["all"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["all"],
      "field_security" : { // optional
        "grant" : [ "title", "body" ]
      },
      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
    }
  ],
  "applications": [
    {
      "application": "myapp",
      "privileges": [ "admin", "read" ],
      "resources": [ "*" ]
    }
  ],
  "run_as": [ "other_user" ], // optional
  "metadata" : { // optional
    "version" : 1
  }
}
--------------------------------------------------

A successful call returns a JSON structure that shows whether the role has been
created or updated.

[source,console-result]
--------------------------------------------------
{
  "role": {
    "created": true <1>
  }
}
--------------------------------------------------

<1> When an existing role is updated, `created` is set to false.