Create or update users

Auth

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 enum · default: true

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: true false wait_for

Request body

username string
email union string nullable

The email of the user.

One of: string
full_name union string nullable

The full name of the user.

One of: string
metadata object

Arbitrary metadata that you want to associate with the user.

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

Reference
roles 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 · default: true

Specifies whether the user is enabled.

Response

application/json
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.