Find roles with a query Added in 8.15.0

POST /_security/_query/role
Api key auth

Get roles in a paginated manner. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. You can optionally filter the results with a query. Also, the results can be paginated and sorted.

application/json

Body

  • query object

    Additional properties are allowed.

    Hide query attributes Show query attributes object
    • bool
    • exists
    • ids
    • match object

      Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.

    • match_all
    • prefix object

      Returns roles that contain a specific prefix in a provided field.

    • range object

      Returns roles that contain terms within a provided range.

    • simple_query_string
    • term object

      Returns roles that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.

    • terms
    • wildcard object

      Returns roles that contain terms matching a wildcard pattern.

  • from number

    The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort string | object | array[string | object]

    One of:
    _types:Field string _types:SortOptions object _types:Sort array[string | object]

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • size number

    The number of hits to return. It must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • search_after array[number | string | boolean | null]

    A field value.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • total number Required

      The total number of roles found.

    • count number Required

      The number of roles returned in the response.

    • roles array[object] Required

      A list of roles that match the query. The returned role format is an extension of the role definition format. It adds the transient_metadata.enabled and the _sort fields. transient_metadata.enabled is set to false in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license. _sort is present when the search query sorts on some field. It contains the array of values that have been used for sorting.

      Hide roles attributes Show roles attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

        Hide indices attributes Show indices attributes object
      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

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

        • resources array[string] Required

          A list resources to which the privileges are applied.

      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

      • run_as array[string]

        A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

      • description string

        Optional description of the role descriptor

      • restriction object

        Additional properties are allowed.

        Hide restriction attribute Show restriction attribute object
        • workflows array[string] Required

          A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

      • transient_metadata object
        Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

      • _sort array[number | string | boolean | null]

        A field value.

      • name string Required

        Name of the role.
POST /_security/_query/role 
curl \
 --request POST http://api.example.com/_security/_query/role \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":{"match":{},"prefix":{},"range":{},"term":{},"wildcard":{}},"from":42.0,"":"string","size":42.0,"search_after":[42.0]}'