# Create or update users


**POST /_security/user/{username}**

**All methods and paths for this operation:**

<div>
                      <span class="operation-verb put">PUT</span>
                      <span class="operation-path">/_security/user/{username}</span>
                      </div>
                    <div>
                      <span class="operation-verb post">POST</span>
                      <span class="operation-path">/_security/user/{username}</span>
                      </div>
                    

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`



## Servers
- http://api.example.com: http://api.example.com ()


## Authentication methods
- Api key auth
- Basic auth
- Bearer auth


## Parameters

### 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.

### 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.

### Body: application/json (object)

- **username** (string)

- **email** (string | null)
  The email of the user.
- **full_name** (string | null)
  The full name of the user.
- **metadata** (object)
  Arbitrary metadata that you want to associate with the user.
- **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.
- **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


#### Body: application/json (object)
- **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`.


[Powered by Bump.sh](https://bump.sh)