[role="xpack"]
[[security-api-users]]
=== User Management APIs

The `user` API enables you to create, read, update, and delete users from the
`native` realm. These users are commonly referred to as *native users*.
To use this API, you must have at least the `manage_security` cluster privilege.

[[security-api-put-user]]
To add a user, submit a PUT or POST request to the `/_xpack/security/user/<username>`
endpoint.

[[username-validation]]
NOTE: Usernames must be at least 1 and no more than 1024 characters. They can
      contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces,
      punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
      Leading or trailing whitespace is not allowed.

[source,js]
--------------------------------------------------
POST /_xpack/security/user/jacknich
{
  "password" : "j@rV1s",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "jacknich@example.com",
  "metadata" : {
    "intelligence" : 7
  }
}
--------------------------------------------------
// CONSOLE

.User Fields
[cols="4,^2,10"]
|=======================
| Name        | Required  | Description
| `password`  | yes       | The user's password. Passwords must be at least 6
                            characters long.
| `roles`     | yes       | A set of roles the user has. The roles determine
                            the user's access permissions
| `full_name` | no        | The full name of the user
| `email`     | no        | The email of the user
| `metadata`  | no        | Arbitrary metadata that you want to associate with
                            the user.
|=======================

A successful call returns a JSON structure that shows whether the user has been
created or updated.

[source,js]
--------------------------------------------------
{
  "user": {
    "created" : true <1>
  }
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing user is updated, `created` is set to false.

NOTE: You also use the PUT user API to update users. When updating a user, you
      can update everything but its `username` and `password`. To change a user's
      password, use the  <<security-api-reset-user-password, reset password API>>.

Once you add a user through the Users API, requests from that user can be
authenticated.

[source,shell]
--------------------------------------------------
curl -u eustace:secret-password http://localhost:9200/_cluster/health
--------------------------------------------------

[[security-api-get-user]]
To retrieve a native user, submit a GET request to the `/_xpack/security/user/<username>`
endpoint:

[source,js]
--------------------------------------------------
GET /_xpack/security/user/jacknich
--------------------------------------------------
// CONSOLE
// TEST[continued]

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

[source,js]
--------------------------------------------------
{
  "jacknich": {  <1>
    "username" : "jacknich",
    "roles" : [ "admin", "other_role1" ],
    "full_name" : "Jack Nicholson",
    "email" : "jacknich@example.com",
    "enabled": true,
    "metadata" : {
      "intelligence" : 7
    }
  }
}
--------------------------------------------------
// TESTRESPONSE
<1> If the user is not defined in the `native` realm, the request 404s.

You can specify multiple usernames as a comma-separated list:

[source,js]
--------------------------------------------------
GET /_xpack/security/user/jacknich,rdinero
--------------------------------------------------
// CONSOLE
// TEST[continued]

or omit the username all together to retrieve all users:

[source,js]
--------------------------------------------------
GET /_xpack/security/user
--------------------------------------------------
// CONSOLE
// TEST[continued]

[[security-api-reset-user-password]]
To reset the password for a user, submit a PUT request to the
`/_xpack/security/user/<username>/_password` endpoint:

[source,js]
--------------------------------------------------
PUT /_xpack/security/user/jacknich/_password
{
  "password" : "s3cr3t"
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

[[security-api-disable-user]]
To disable a user, submit a PUT request to the
`/_xpack/security/user/<username>/_disable` endpoint:

[source,js]
--------------------------------------------------
PUT /_xpack/security/user/jacknich/_disable
--------------------------------------------------
// CONSOLE
// TEST[continued]

[[security-api-enable-user]]
To enable a user, submit a PUT request to the
`/_xpack/security/user/<username>/_enable` endpoint:

[source,js]
--------------------------------------------------
PUT /_xpack/security/user/jacknich/_enable
--------------------------------------------------
// CONSOLE
// TEST[continued]

[[security-api-delete-user]]
To delete a user, submit a DELETE request to the `/_xpack/security/user/<username>`
endpoint:

[source,js]
--------------------------------------------------
DELETE /_xpack/security/user/jacknich
--------------------------------------------------
// CONSOLE
// TEST[continued]

If the user is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.

[source,js]
--------------------------------------------------
{
  "found" : true
}
--------------------------------------------------
// TESTRESPONSE