elasticsearch/docs/reference/rest-api/security/get-users.asciidoc

[role="xpack"]
[[security-api-get-user]]
=== Get users API
++++
<titleabbrev>Get users</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

Retrieves information about users in the native realm and built-in users.

[[security-api-get-user-request]]
==== {api-request-title}

`GET /_security/user` +

`GET /_security/user/<username>`

[[security-api-get-user-prereqs]]
==== {api-prereq-title}

* To use this API, you must have at least the `read_security` cluster privilege.


[[security-api-get-user-desc]]
==== {api-description-title}

For more information about the native realm, see
<<realms>> and <<native-realm>>.

[[security-api-get-user-path-params]]
==== {api-path-parms-title}

`username`::
  (Optional, string) An identifier for the user. You can specify multiple
  usernames as a comma-separated list. If you omit this parameter, the API
  retrieves information about all users.

[[security-api-get-user-query-params]]
==== {api-query-parms-title}

`with_profile_uid`::
(Optional, boolean) Determines whether to retrieve the <<user-profile,user profile>> `uid`,
if exists, for the users. Defaults to `false`.

[[security-api-get-user-response-body]]
==== {api-response-body-title}

A successful call returns an array of users with the JSON representation of the
users. Note that user passwords are not included.

[[security-api-get-user-response-codes]]
==== {api-response-codes-title}

If the user is not defined in the `native` realm, the request 404s.

[[security-api-get-user-example]]
==== {api-examples-title}

To retrieve a native user, submit a GET request to the `/_security/user/<username>`
endpoint:

[source,console]
--------------------------------------------------
GET /_security/user/jacknich
--------------------------------------------------
// TEST[setup:jacknich_user]

[source,console-result]
--------------------------------------------------
{
  "jacknich": {
    "username": "jacknich",
    "roles": [
      "admin", "other_role1"
    ],
    "full_name": "Jack Nicholson",
    "email": "jacknich@example.com",
    "metadata": { "intelligence" : 7 },
    "enabled": true
  }
}
--------------------------------------------------

To retrieve the user `profile_uid` as part of the response:

[source,console]
--------------------------------------------------
GET /_security/user/jacknich?with_profile_uid=true
--------------------------------------------------
// TEST[continued]

[source,console-result]
--------------------------------------------------
{
  "jacknich": {
    "username": "jacknich",
    "roles": [
      "admin", "other_role1"
    ],
    "full_name": "Jack Nicholson",
    "email": "jacknich@example.com",
    "metadata": { "intelligence" : 7 },
    "enabled": true,
    "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
  }
}
--------------------------------------------------


Omit the username to retrieve all users:

[source,console]
--------------------------------------------------
GET /_security/user
--------------------------------------------------
// TEST[continued]