Find users with a query

POST also GET /_security/_query/user

Get information for users in a paginated manner. You can optionally filter the results with a query.

Note

As opposed to the get user API, built-in users are excluded from the result. This API is only for native users.

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Request body

query object: A query to filter which users to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following information associated with user: username, roles, enabled, full_name, and email.
from number · default: 0: 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 union: The sort definition. Fields eligible for sorting are: username, roles, enabled. In addition, sort can also be applied to the _doc field to sort by index order.; Reference
size number · default: 10: 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 union[]: The search after definition; Reference

A successful response from POST /_security/_query/user?with_profile_uid=true that contains users that have roles that are prefixed with other. It also includes the user profile_uid in the response.

{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        }
    ]
}

Request Console 1 / 2 languages

Run POST /_security/_query/user. Use a bool query to issue complex logical conditions: The email must end with example.com. The user must be enabled. The result will be filtered to only contain users with at least one role that contains the substring other. The offset to begin the search result is the second (zero-based index) user. The page size of the response is two users. The result is sorted by username in descending order.

Console Kibana Dev Tools

POST /_security/_query/user
{
  "query": {
    "bool": {
      "must": [
        {
          "wildcard": {
            "email": "*example.com" 
          }
        },
        {
          "term": {
            "enabled": true 
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "roles": "*other*" 
          }
        }
      ]
    }
  },
  "from": 1, 
  "size": 2, 
  "sort": [
    { "username": { "order": "desc"} } 
  ]
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/user" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must": [
          {
            "wildcard": {
              "email": "*example.com" 
            }
          },
          {
            "term": {
              "enabled": true 
            }
          }
        ],
        "filter": [
          {
            "wildcard": {
              "roles": "*other*" 
            }
          }
        ]
      }
    },
    "from": 1, 
    "size": 2, 
    "sort": [
      { "username": { "order": "desc"} } 
    ]
  }'

Generated from the API spec

Response

A successful response from POST /_security/_query/user that uses a bool query to issue complex logical conditions and uses from, size, and sort to help paginate the result. The sort value is username.

{
    "total": 5,
    "count": 2,
    "users": [
        {
            "username": "ray",
            "roles": [
                "other_role3"
            ],
            "full_name": "Ray Nicholson",
            "email": "rayn@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "ray" 
            ]
        },
        {
            "username": "lorraine",
            "roles": [
                "other_role3"
            ],
            "full_name": "Lorraine Nicholson",
            "email": "lorraine@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "lorraine"
            ]
        }
    ]
}

Find users with a query

Required authorization

Authentication

Query parameters

Request body

Response

Required authorization

Authentication

Query parameters

Request body { }

Response

Request body