[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*.


==== Request

`GET /_xpack/security/user` +

`GET /_xpack/security/user/<username>` +

`DELETE /_xpack/security/user/<username>` +

`POST /_xpack/security/user/<username>` +

`PUT /_xpack/security/user/<username>` +

`PUT /_xpack/security/user/<username>/_disable` +

`PUT /_xpack/security/user/<username>/_enable` +

`PUT /_xpack/security/user/<username>/_password`


==== Description

You can use the PUT user API to create or 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>>.

[[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.

==== Path Parameters

`username`::
  (string) An identifier for the user. If you omit this parameter from a Get
  User API request, it retrieves information about all users.


==== Request Body

The following parameters can be specified in the body of a POST or PUT request
and pertain to creating a user:

`enabled`::
(boolean) Specifies whether the user is enabled. The default value is `true`.

`email`::
(string) The email of the user.

`full_name`::
(string) The full name of the user.

`metadata`::
(object) Arbitrary metadata that you want to associate with the user.

`password` (required)::
(string) The user's password. Passwords must be at least 6 characters long. 

`roles` (required)::
(list) A set of roles the user has. The roles determine the user's access 
permissions. To create a user without any roles, specify an empty list: `[]`.

==== Authorization

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


==== Examples

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

[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

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.

After you add a user through the Users API, requests from that user can be
authenticated. For example:

[source,shell]
--------------------------------------------------
curl -u jacknich:j@rV1s 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]

Omit the username 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