IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Create or update roles API Delete role mappings API »

› › ›

Create or update users API

edit

Create or update users API

edit

Adds and updates users in the native realm. These users are commonly referred to as native users.

Request

edit

POST /_xpack/security/user/<username>

PUT /_xpack/security/user/<username>

Description

edit

When updating a user, you can update everything but its username and password. To change a user’s password, use the change password API.

For more information about the native realm, see Realms and Configuring a native realm.

Path Parameters

edit

username (required): (string) An identifier for the user.

Usernames must be at least 1 and no more than 1024 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.

Request Body

edit

The following parameters can be specified in the body of a POST or PUT request:

enabled: (boolean) Specifies whether the user is enabled. The default value is true.
email: (string) The email of the user.
full_name: (string) The full name of the user.
metadata: (object) Arbitrary metadata that you want to associate with the user.
password (required): (string) The user’s password. Passwords must be at least 6 characters long.
roles (required): (list) 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: [].

Authorization

edit

To use this API, you must have at least the manage_security cluster privilege.

Examples

edit

The following example creates a user jacknich:

POST /_xpack/security/user/jacknich
{
  "password" : "j@rV1s",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "jacknich@example.com",
  "metadata" : {
    "intelligence" : 7
  }
}

A successful call returns a JSON structure that shows whether the user has been created or updated.

{
  "user": {
    "created" : true 
  }
}

When an existing user is updated, created is set to false.

After you add a user, requests from that user can be authenticated. For example:

curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health

« Create or update roles API Delete role mappings API »