[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 management APIs are generally the preferred way to manage roles, rather than using
<<roles-management-file,file-based role management>>. The create
or update roles API cannot update roles that are defined in roles files.

[[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`::: (object) The document fields that the owners of the role have
read access to. For more information, see
<<field-and-document-access-control>>.
`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
<<run-as-privilege>>.

`remote_indices`:: beta:[] (list) A list of remote indices permissions entries.
+
--
NOTE: Remote indices are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
They have no effect for remote clusters configured with the <<remote-clusters-cert,certificate based model>>.
--
`clusters` (required)::: (list) A list of cluster aliases to which the permissions
in this entry apply.
`field_security`::: (object) The document fields that the owners of the role have
read access to. For more information, see
<<field-and-document-access-control>>.
`names` (required)::: (list) A list of indices (or index name patterns) on the remote clusters
(specified with `clusters`) 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.

For more information, see <<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.

The following example configures a role that can run SQL in JDBC:

// tag::sql-queries-permission[]
[source,console]
--------------------------------------------------
POST /_security/role/cli_or_drivers_minimal
{
  "cluster": ["cluster:monitor/main"],
  "indices": [
    {
      "names": ["test"],
      "privileges": ["read", "indices:admin/get"]
    }
  ]
}
--------------------------------------------------
// end::sql-queries-permission[]

The following example configures a role with remote indices privileges on a remote cluster:
[source,console]
--------------------------------------------------
POST /_security/role/role_with_remote_indices
{
  "remote_indices": [
    {
      "clusters": [ "my_remote" ], <1>
      "names": ["logs*"], <2>
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] <3>
    }
  ]
}
--------------------------------------------------

<1> The remote indices privileges apply to remote cluster with the alias `my_remote`.
<2> Privileges are granted for indices matching pattern `logs*` on the remote cluster ( `my_remote`).
<3> The actual <<privileges-list-indices,index privileges>> granted for `logs*` on `my_remote`.