› › ›

Get roles API

Retrieves roles in the native realm.

Request

GET /_security/role

GET /_security/role/<name>

Prerequisites

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

Description

The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The get roles API cannot retrieve roles that are defined in roles files.

Path parameters

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.

Response body

A successful call returns an array of roles with the JSON representation of the role.

Response codes

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

Examples

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

GET /_security/role/my_admin_role

{
  "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
    }
  }
}

To retrieve all roles, omit the role name:

GET /_security/role

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-api-get-role.html