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

[role="xpack"]
[[security-api-put-user]]
=== Create or update users API
++++
<titleabbrev>Create or update users</titleabbrev>
++++

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


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

`POST /_security/user/<username>` +

`PUT /_security/user/<username>`


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

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


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

A `password` is required for adding a new user but is optional when updating an
existing user. To change a user's password without updating any other fields,
use the <<security-api-change-password, change password API>>.

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

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

`username`::
  (Required, string) An identifier for the user.
+
--
[[username-validation]]
NOTE: Usernames must be at least 1 and no more than 507 characters. They can
contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and
printable symbols in the {wikipedia}/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed.

--

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

`refresh`::
    (string) One of `true`, `false`, or `wait_for`.
    These values have the same meaning as in the <<docs-refresh, Index API>>,
    but the default value for this API (Put User) is `true`.

[[security-api-put-user-request-body]]
==== {api-request-body-title}

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<<not-always-required,*>>, string) The user's password. Passwords must be at least 6 characters long.
+
When adding a user, one of `password` or `password_hash` is required.
When updating an existing user, the password is optional, so that other
fields on the user (such as their roles) may be updated without modifying
the user's password.

`password_hash`::
(string) A _hash_ of the user's password. This must be produced using the
same hashing algorithm as has been configured for password storage. For more
details, see the explanation of the
`xpack.security.authc.password_hashing.algorithm` setting in
<<hashing-settings>>.
+
Using this parameter allows the client to pre-hash the password for
performance and/or confidentiality reasons.
+
The `password` parameter and the `password_hash` parameter cannot be
used in the same request.

`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:
`[]`.

--
[[not-always-required]]
*Indicates that the setting is required in some, but not all situations.
--

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

The following example creates a user `jacknich`:

[source,console]
--------------------------------------------------
POST /_security/user/jacknich
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "jacknich@example.com",
  "metadata" : {
    "intelligence" : 7
  }
}
--------------------------------------------------

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

[source,console-result]
--------------------------------------------------
{
  "created": true <1>
}
--------------------------------------------------

<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:l0ng-r4nd0m-p@ssw0rd http://localhost:9200/_cluster/health
--------------------------------------------------
// NOTCONSOLE