Create or update users Generally available

POST /_security/user/{username}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /_security/user/{username}

POST /_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

    Arbitrary metadata that you want to associate with the user.

    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • 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.

    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.

    Default value is true.

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.
POST /_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"
client.security().putUser(p -> p
    .email("jacknich@example.com")
    .fullName("Jack Nicholson")
    .metadata("intelligence", JsonData.fromJson("7"))
    .password("l0ng-r4nd0m-p@ssw0rd")
    .roles(List.of("admin","other_role1"))
    .username("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 
}