---
type: api
title: Create or update users
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-put-user
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-put-user
products:
  - Elasticsearch
---

# Create or update users


Availability:

## Paths

- `POST` (also `PUT`) `/_security/user/{username}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

#### Path Parameters

- `username` (string)
  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.

## Description

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`

## Query String 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 Body

`application/json`

- `username` (string) — optional
- `email` (union string) — optional — nullable
  The email of the user.
  One of: `string`
- `full_name` (union string) — optional — nullable
  The full name of the user.
  One of: `string`
- `metadata` (Metadata) — optional
  Arbitrary metadata that you want to associate with the user.
- `password` (string) — optional
  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) — optional
  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.
- `roles` ([] string) — optional
  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 · default: true) — optional
  Specifies whether the user is enabled.

## Response

`application/json`

- `created` (boolean)
  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`.
## Code Examples

#### Console

```console
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

```javascript
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

```python
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

```curl
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

```java
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#

```c#
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

```php
$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

```ruby
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 Examples

#### Security put user response example1

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

```json
{
  "created": true 
}
```