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

[role="xpack"]
[[security-api-get-role]]
=== Get roles API
++++
<titleabbrev>Get roles</titleabbrev>
++++

Retrieves roles in the native realm.

==== Request

`GET /_security/role` +

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

==== Description

For more information about the native realm, see 
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 

==== Path Parameters

`name`::
  (string) The name of the role. You can specify multiple roles as a 
  comma-separated list. If you do not specify this parameter, the API 
  returns information about all roles.

//==== Request Body

==== Authorization

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


==== Examples

The following example retrieves information about the `my_admin_role` role in 
the native realm:

[source,js]
--------------------------------------------------
GET /_security/role/my_admin_role
--------------------------------------------------
// CONSOLE
// TEST[setup:admin_role]

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 returns 404.

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

To retrieve all roles, omit the role name:

[source,js]
--------------------------------------------------
GET /_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.