Get roles

GET /_security/role/{name}
GET /_security/role

Auth

Get roles in the native realm. 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.

Required authorization

Cluster privileges read_security

Path parameters

name union string | string[] optional

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.

Leave it out to use /_security/role.

Query parameters

include_implicit boolean · default: false: If true, include privileges that are implicitly granted by registered ImplicitPrivilegesProviders alongside the explicitly configured privileges. Each implicit entry in the response is annotated with implicitly_granted: true.

Response

application/json

<string> object

Examples

Request Console 1 / 8 languages

Console Kibana Dev Tools

GET /_security/role/my_admin_role

JavaScript Elasticsearch JavaScript Client

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

Python Elasticsearch Python Client

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

curl Shell

curl -X GET "$ELASTICSEARCH_URL/_security/role/my_admin_role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"

Java Elasticsearch Java Client

client.security().getRole(g -> g
    .name("my_admin_role")
);

C# Elasticsearch .NET Client

var response = await client.Security
    .GetRoleAsync(d1 => d1
        .Name(new[] { "my_admin_role" })
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->getRole([
    "name" => "my_admin_role",
]);

Ruby Elasticsearch Ruby Client

response = client.security.get_role(
  name: "my_admin_role"
)

Response

A successful response from GET /_security/role/my_admin_role. The response contains information about the my_admin_role role in the native realm.

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