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

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Path parameters

Query parameters

Request body

Response

application/json

Examples

Request Console 1 / 8 languages

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

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

A successful response from POST /_security/user/jacknich. When an existing user is updated, created is set to false.

{
  "created": true 
}

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body