Create or update users

PUT /_security/user/{username}
Api key auth Basic auth Bearer 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.

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} 
curl \
 --request PUT 'http://api.example.com/_security/user/{username}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"password\" : \"l0ng-r4nd0m-p@ssw0rd\",\n  \"roles\" : [ \"admin\", \"other_role1\" ],\n  \"full_name\" : \"Jack Nicholson\",\n  \"email\" : \"jacknich@example.com\",\n  \"metadata\" : {\n    \"intelligence\" : 7\n  }\n}"'
Request example
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 
}