OpenSearch/x-pack/docs/en/rest-api/security/roles.asciidoc

[role="xpack"]
[[security-api-roles]]
=== Role Management APIs

The Roles API enables you to add, remove, and retrieve roles in the `native`
realm.

==== Request

`GET /_xpack/security/role` +

`GET /_xpack/security/role/<name>` +

`POST /_xpack/security/role/<name>/_clear_cache` +

`POST /_xpack/security/role/<name>` +

`PUT /_xpack/security/role/<name>`


==== Description

The Roles API is generally the preferred way to manage roles, rather than using
file-based role management. For more information, see
{xpack-ref}/authorization.html[Configuring Role-based Access Control].


==== Path Parameters

`name`::
  (string) The name of the role. If you do not specify this parameter, the
  Get Roles API returns information about all roles.


==== Request Body

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

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

`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
{xpack-ref}/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
{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].

For more information, see {xpack-ref}/defining-roles.html[Defining Roles].


==== Authorization

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


==== Examples

[[security-api-put-role]]
To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
endpoint:

[source,js]
--------------------------------------------------
POST /_xpack/security/role/my_admin_role
{
  "cluster": ["all"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["all"],
      "field_security" : { // optional
        "grant" : [ "title", "body" ]
      },
      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
    }
  ],
  "run_as": [ "other_user" ], // optional
  "metadata" : { // optional
    "version" : 1
  }
}
--------------------------------------------------
// CONSOLE

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

[source,js]
--------------------------------------------------
{
  "role": {
    "created": true <1>
  }
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing role is updated, `created` is set to false.

[[security-api-get-role]]
To retrieve a role from the `native` Security realm, issue a GET request to the
`/_xpack/security/role/<rolename>` endpoint:

[source,js]
--------------------------------------------------
GET /_xpack/security/role/my_admin_role
--------------------------------------------------
// CONSOLE
// TEST[continued]

A successful call returns an array of roles with the JSON representation of the
role. If the role is not defined in the `native` realm, the request 404s.

[source,js]
--------------------------------------------------
{
  "my_admin_role": {
    "cluster" : [ "all" ],
    "indices" : [ {
      "names" : [ "index1", "index2" ],
      "privileges" : [ "all" ],
      "field_security" : {
        "grant" : [ "title", "body" ]
      },
      "query" : "{\"match\": {\"title\": \"foo\"}}"
    } ],
    "run_as" : [ "other_user" ],
    "metadata" : {
      "version" : 1
    },
    "transient_metadata": {
      "enabled": true
    }
  }
}
--------------------------------------------------
// TESTRESPONSE

You can specify multiple roles as a comma-separated list. To retrieve all roles,
omit the role name.

[source,js]
--------------------------------------------------
# Retrieve roles "r1", "r2", and "my_admin_role"
GET /_xpack/security/role/r1,r2,my_admin_role

# Retrieve all roles
GET /_xpack/security/role
--------------------------------------------------
// CONSOLE
// TEST[continued]

NOTE: If single role is requested, that role is returned as the response. When 
requesting multiple roles, an object is returned holding the found roles, each 
keyed by the relevant role name.

[[security-api-delete-role]]
To delete a role, submit a DELETE request to the `/_xpack/security/role/<rolename>`
endpoint:

[source,js]
--------------------------------------------------
DELETE /_xpack/security/role/my_admin_role
--------------------------------------------------
// CONSOLE
// TEST[continued]

If the role is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.

[source,js]
--------------------------------------------------
{
  "found" : true
}
--------------------------------------------------
// TESTRESPONSE

[[security-api-clear-role-cache]]
The Clear Roles Cache API evicts roles from the native role cache. To clear the
cache for a role, submit a POST request `/_xpack/security/role/<rolename>/_clear_cache`
endpoint:

[source,js]
--------------------------------------------------
POST /_xpack/security/role/my_admin_role/_clear_cache
--------------------------------------------------
// CONSOLE