Create or update users

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.

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

      Additional properties are allowed.

  • password 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 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}
curl \
 -X POST http://api.example.com/_security/user/{username} \
 -H "Content-Type: application/json" \
 -d '{"username":"string","email":"string","full_name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}},"password":"string","password_hash":"string","roles":["string"],"enabled":true}'
Request examples
{
  "username": "string",
  "email": "string",
  "full_name": "string",
  "metadata": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "password": "string",
  "password_hash": "string",
  "roles": [
    "string"
  ],
  "enabled": true
}
Response examples (200)
{
  "created": true
}