elasticsearch/docs/reference/rest-api/security/get-roles.asciidoc

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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

Retrieves roles in the native realm.

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

`GET /_security/role` +

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

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

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

[[security-api-get-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 get roles
API cannot retrieve roles that are defined in roles files.

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

`name`::
  (Optional, 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.

[[security-api-get-role-response-body]]
==== {api-response-body-title}

A successful call returns an array of roles with the JSON representation of the
role. The returned role format is a simple extension of the <<defining-roles,role definition>> format,
only adding an extra field `transient_metadata.enabled`.
This field is `false` in case the role is automatically disabled, for example when the license
level does not allow some permissions that the role grants.

[[security-api-get-role-response-codes]]
==== {api-response-codes-title}

If the role is not defined in the native realm, the request returns 404.

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

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

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

[source,console-result]
--------------------------------------------------
{
  "my_admin_role": {
    "description": "Grants full access to all management features within the cluster.",
    "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
    }
  }
}
--------------------------------------------------

To retrieve all roles, omit the role name:

[source,console]
--------------------------------------------------
GET /_security/role
--------------------------------------------------
// TEST[continued]