Create or update users Generally available

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.

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/jacknich { "password" : "l0ng-r4nd0m-p@ssw0rd", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "metadata" : { "intelligence" : 7 } }
resp = client.security.put_user( username="jacknich", password="l0ng-r4nd0m-p@ssw0rd", roles=[ "admin", "other_role1" ], full_name="Jack Nicholson", email="jacknich@example.com", metadata={ "intelligence": 7 }, )
const response = await client.security.putUser({ username: "jacknich", password: "l0ng-r4nd0m-p@ssw0rd", roles: ["admin", "other_role1"], full_name: "Jack Nicholson", email: "jacknich@example.com", metadata: { intelligence: 7, }, });
response = client.security.put_user( username: "jacknich", body: { "password": "l0ng-r4nd0m-p@ssw0rd", "roles": [ "admin", "other_role1" ], "full_name": "Jack Nicholson", "email": "jacknich@example.com", "metadata": { "intelligence": 7 } } )
$resp = $client->security()->putUser([ "username" => "jacknich", "body" => [ "password" => "l0ng-r4nd0m-p@ssw0rd", "roles" => array( "admin", "other_role1", ), "full_name" => "Jack Nicholson", "email" => "jacknich@example.com", "metadata" => [ "intelligence" => 7, ], ], ]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"password":"l0ng-r4nd0m-p@ssw0rd","roles":["admin","other_role1"],"full_name":"Jack Nicholson","email":"jacknich@example.com","metadata":{"intelligence":7}}' "$ELASTICSEARCH_URL/_security/user/jacknich"
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 }