Get roles API

GET /_security/role

GET /_security/role/<name>

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.

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

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

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

resp = client.security.get_role(
    name="my_admin_role",
)
print(resp)

const response = await client.security.getRole({
  name: "my_admin_role",
});
console.log(response);

GET /_security/role/my_admin_role

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

resp = client.security.get_role()
print(resp)

const response = await client.security.getRole();
console.log(response);

GET /_security/role