Find roles with a query | Elasticsearch API documentation (v8)

application/json

Body

queryobject
Hide query attributes Show query attributes object
- bool
- exists
- ids
- matchobject
  Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
- match_all
- prefixobject
  Returns roles that contain a specific prefix in a provided field.
- rangeobject
  Returns roles that contain terms within a provided range.
- simple_query_string
- termobject
  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
- wildcardobject
  Returns roles that contain terms matching a wildcard pattern.
fromnumber
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.
sortstring | object | array[string | object]
One of:
Fieldstring SortOptionsobject Sortarray[string | object]
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
_scoreobject
Hide _score attribute Show _score attribute object
orderstring
Values are asc or desc.
_docobject
Hide _doc attribute Show _doc attribute object
orderstring
Values are asc or desc.
_geo_distanceobject
Hide _geo_distance attributes Show _geo_distance attributes object
modestring
Values are min, max, sum, avg, or median.
distance_typestring
Values are arc or plane.
ignore_unmappedboolean
orderstring
Values are asc or desc.
unitstring
Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_scriptobject
Hide _script attributes Show _script attributes object
orderstring
Values are asc or desc.
scriptobject Required
Hide script attributes Show script attributes object
sourcestring
The script source.
idstring
paramsobject
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
Hide params attribute Show params attribute object
*object Additional properties
langstring
Any of:
ScriptLanguagestring ScriptLanguagestring
Values are painless, expression, mustache, or java.
optionsobject
Hide options attribute Show options attribute object
*string Additional properties
typestring
Values are string, number, or version.
modestring
Values are min, max, sum, avg, or median.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Fieldstring SortOptionsobject
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
_scoreobject
Hide _score attribute Show _score attribute object
orderstring
Values are asc or desc.
_docobject
Hide _doc attribute Show _doc attribute object
orderstring
Values are asc or desc.
_geo_distanceobject
Hide _geo_distance attributes Show _geo_distance attributes object
modestring
Values are min, max, sum, avg, or median.
distance_typestring
Values are arc or plane.
ignore_unmappedboolean
orderstring
Values are asc or desc.
unitstring
Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_scriptobject
Hide _script attributes Show _script attributes object
orderstring
Values are asc or desc.
scriptobject Required
Hide script attributes Show script attributes object
sourcestring
The script source.
idstring
paramsobject
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
lang
optionsobject
typestring
Values are string, number, or version.
modestring
Values are min, max, sum, avg, or median.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
sizenumber
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_afterarray[number | string | boolean | null | object]
A field value.
A field value.
One of:
FieldValuenumber FieldValuenumber FieldValuestring FieldValueboolean FieldValuestring | null FieldValueobject

Responses

200 application/json
Hide response attributes Show response attributes object
- totalnumber Required
  The total number of roles found.
- countnumber Required
  The number of roles returned in the response.
- rolesarray[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
  clusterarray[string]
  A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
  indicesarray[object]
  A list of indices permissions entries.
  Hide indices attributes Show indices attributes object
  field_securityobject
  namesarray[string] Required
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  privilegesarray[string] Required
  The index level privileges that owners of the role have on the specified indices.
  query
  allow_restricted_indicesboolean
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  remote_indicesarray[object]
  A list of indices permissions for remote clusters.
  Hide remote_indices attributes Show remote_indices attributes object
  clustersstring | array[string] Required
  field_securityobject
  namesarray[string] Required
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  privilegesarray[string] Required
  The index level privileges that owners of the role have on the specified indices.
  query
  allow_restricted_indicesboolean
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  remote_clusterarray[object]
  A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.
  Hide remote_cluster attributes Show remote_cluster attributes object
  clustersstring | array[string] Required
  privilegesarray[string] Required
  The cluster level privileges that owners of the role have on the remote cluster.
  Values are monitor_enrich or monitor_stats.
  globalarray[object] | object
  An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
  One of:
  array-1array[object]GlobalPrivilegeobject
  applicationsarray[object]
  A list of application privilege entries
  Hide applications attributes Show applications attributes object
  applicationstring Required
  The name of the application to which this entry applies.
  privilegesarray[string] Required
  A list of strings, where each element is the name of an application privilege or action.
  resourcesarray[string] Required
  A list resources to which the privileges are applied.
  metadataobject
  Hide metadata attribute Show metadata attribute object
  run_asarray[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.
  descriptionstring
  Optional description of the role descriptor
  restrictionobject
  Hide restriction attribute Show restriction attribute object
  workflowsarray[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_metadataobject
  Hide transient_metadata attribute Show transient_metadata attribute object
  _sortarray[number | string | boolean | null | object]
  A field value.
  A field value.
  One of:
  FieldValuenumber FieldValuenumber FieldValuestring FieldValueboolean FieldValuestring | null FieldValueobject
  namestring Required
  Name of the role.

GET /_security/_query/role

curl \
 --request GET 'http://api.example.com/_security/_query/role' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"sort\": [\"name\"]\n}"'

Request examples

Run `POST /_security/_query/role` to lists all roles, sorted by the role name.

{
    "sort": ["name"]
}

Run `POST /_security/_query/role` to query only the user access role, given its description. It returns only the best matching role because `size` is set to `1`.

{
  "query": {
    "match": {
      "description": {
        "query": "user access"
      }
    }
  },
  "size": 1 
}

Response examples (200)

A successful response from `POST /_security/_query/role`. It returns a JSON structure that contains the information retrieved for one or more roles.

{
    "total": 2,
    "count": 2,
    "roles": [ 
        {
          "name" : "my_admin_role",
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [
            "other_user"
          ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants full access to all management features within the cluster.",
          "_sort" : [
            "my_admin_role"
          ]
        },
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies.",
          "_sort" : [
            "my_user_role"
          ]
        }
    ]
}

A successful response from `POST /_security/_query/role`.

{
    "total": 2,
    "count": 1,
    "roles": [
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies."
        }
    ]
}

Body

sortstring | object | array[string | object]

langstring

Responses

globalarray[object] | object