Create or update users

POST also 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 enum Refresh · 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

Response

application/json

Examples

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

Request Console 1 / 8 languages

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

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,
  },
});

Python Elasticsearch Python Client

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
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/user/jacknich" \
  -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
    }
  }'

Java Elasticsearch Java Client

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")
);

C# Elasticsearch .NET Client

var response = await client.Security
    .PutUserAsync(username: "jacknich", d1 => d1
        .Email("jacknich@example.com")
        .FullName("Jack Nicholson")
        .Metadata(new Dictionary<string, object>()
        {
            { "intelligence", 7 }
        })
        .Password("l0ng-r4nd0m-p@ssw0rd")
        .Roles("admin", "other_role1")
    );

PHP Elasticsearch PHP Client

$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,
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

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
    }
  }
)

Response

{
  "created": true 
}

Required authorization

Path Parameters

Query Parameters

Request { username , email , full_name , metadata , password , password_hash , roles , enabled , }

Response

Request