Create or update users | Elasticsearch API documentation (8x-unreleased)

Create or update users Generally available

PUT /_security/user/{username}

Add and update users in the native realm. 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 change password API. ##Required authorization

Cluster privileges: manage_security

Path parameters

username string Required

An identifier for the user.

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 Basic Latin (ASCII) block. Leading or trailing whitespace is not allowed.

Query parameters

refresh string

Valid values are true, false, and wait_for. These values have the same meaning as in the index API, but the default value for this API is true.

Values are true, false, or wait_for.

application/json

Body Required

username string
email string | null

The email of the user.

One of:
string-1 string string-2 string | null
full_name string | null

The full name of the user.

One of:
string-1 string string-2 string | null
metadata object
Hide metadata attribute Show metadata attribute object
- * object Additional properties
password string
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 the user cache and password hash algorithm documentation. 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.

External documentation
roles array[string]

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 ([]).
enabled boolean

Specifies whether the user is enabled.

Responses

200 application/json
Hide response attribute Show response attribute object
- created boolean Required
  
  A successful call returns a JSON structure that shows whether the user has been created or updated. When an existing user is updated, created is set to false.

PUT /_security/user/{username}

POST /_security/user/cross-cluster-user
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "remote-replication" ]
}

curl \
 --request PUT 'http://api.example.com/_security/user/{username}' \
 --header "Content-Type: application/json" \
 --data '"{\n  \"password\" : \"l0ng-r4nd0m-p@ssw0rd\",\n  \"roles\" : [ \"remote-replication\" ]\n}"'

Request examples

An example body for a `POST /_security/user/cross-cluster-user` request.

{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "remote-replication" ]
}

Run `POST /_security/user/jacknich` to activate a user profile.

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

Response examples (200)

A successful response from `POST /_security/user/jacknich`. When an existing user is updated, `created` is set to `false`.

{
  "created": true 
}

Documentation preview

This is a preview of your version @2025-06-09 which is not yet released.

View current documentation