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 privileges

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
cluster union anyOf[] required
Values: all cancel_task manage manage_api_key manage_behavioral_analytics manage_enrich manage_esql manage_index_templates manage_inference manage_ingest_pipelines manage_logstash_pipelines manage_ml
indices object[] required
implicitly_granted boolean

Set to true on entries that were contributed by a registered ImplicitPrivilegesProvider rather than explicitly stored on the role. Only present when the get role API is called with include_implicit=true. The put role API rejects this field, so clients must not echo it back on a GET-then-PUT round-trip.

field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

privileges union anyOf[] required

The index level privileges that owners of the role have on the specified indices.

Values: all auto_configure create create_doc create_index create_view delete delete_index delete_view index maintenance manage manage_data_stream_lifecycle manage_view monitor none read read_view_metadata view_index_metadata write
query union oneOf

A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

One of:
metadata object required
description string
run_as string[]
transient_metadata map string to object
applications object[] required
application string required

The name of the application to which this entry applies.

privileges string[] required

A list of strings, where each element is the name of an application privilege or action.

resources string[] required

A list resources to which the privileges are applied.

role_templates object[]
format enum
Values: string json
template string required
global object
application object
manage object

The applications for which application privileges can be managed. Absent when the application section is present but grants no privileges.

applications string[] required
profile object

A privilege that grants the ability to write the data and access sections of user profiles for the specified applications.

write object

The applications for which user profile data can be written. Absent when the profile section is present but grants no privileges.

applications string[] required
role object

A privilege that grants the ability to manage roles that are scoped to the specified indices.

manage object

The index-scoped role management privileges. Absent when the role section is present but grants no privileges.

indices object[] required
names string[] required

A list of indices (or index name patterns) that the owners of the role can manage roles for.

privileges string[] required

The index privileges that the managed roles are allowed to grant on the specified indices.