[role="xpack"]
[[security-api-change-password]]
=== Change passwords API
++++
<titleabbrev>Change passwords</titleabbrev>
++++

Changes the passwords of users in the native realm and built-in users.

[[security-api-change-password-request]]
==== {api-request-title}

`POST /_security/user/_password` +

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


[[security-api-change-password-prereqs]]
==== {api-prereq-title}

* Every user can change their own password. Users with the `manage_security`
privilege can change passwords of other users.

[[security-api-change-password-desc]]
==== {api-description-title}

You can use the <<security-api-put-user,create user API>> to update everything
but a user's `username` and `password`. This API changes a user's password.

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


[[security-api-change-password-path-params]]
==== {api-path-parms-title}

`username`::
  (Optional, string) The user whose password you want to change. If you do not specify
  this parameter, the password is changed for the current user.


[[security-api-change-password-request-body]]
==== {api-request-body-title}

`password` ::
(string) The new password value. Passwords must be at least 6 characters long.
+
One of `password` or `password_hash` is required.

`password_hash` ::
(string) A _hash_ of the new password value. 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.


[[security-api-change-password-example]]
==== {api-examples-title}

The following example updates the password for the `jacknich` user:

[source,console]
--------------------------------------------------
POST /_security/user/jacknich/_password
{
  "password" : "new-test-password"
}
--------------------------------------------------
// TEST[setup:jacknich_user]

A successful call returns an empty JSON structure.

[source,console-result]
--------------------------------------------------
{}
--------------------------------------------------