elasticsearch/x-pack/docs/en/rest-api/security/create-users.asciidoc

[role="xpack"]
[[security-api-put-user]]
=== Create or update users API

Adds and updates users in the native realm. These users are commonly referred 
to as _native users_.


==== Request

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

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


==== Description

When updating a user, you can update everything but its `username` and `password`. 
To change a user's password, use the 
<<security-api-change-password, change password API>>.

For more information about the native realm, see 
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 

==== Path Parameters

`username` (required)::
  (string) An identifier for the user.
+
--
[[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.

--


==== Request Body

The following parameters can be specified in the body of a POST or PUT request:

`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

The following example creates a user `jacknich`:

[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, requests from that user can be authenticated. For example:

[source,shell]
--------------------------------------------------
curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
--------------------------------------------------
// NOTCONSOLE