User Management APIs

The user API enables you to create, read, update, and delete users from the native realm. These users are commonly referred to as native users. To use this API, you must have at least the manage_security cluster privilege.

To add a user, submit a PUT or POST request to the /_xpack/security/user/<username> endpoint.

Note

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.

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

Table 35. User Fields

Name

Required

Description

password

yes

The user’s password. Passwords must be at least 6 characters long.

roles

yes

A set of roles the user has. The roles determine the user’s access permissions

full_name

no

The full name of the user

email

no

The email of the user

metadata

no

Arbitrary metadata that you want to associate with the user.


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.

Note

You also use the PUT user API to update users. When updating a user, you can update everything but its username and password. To change a user’s password, use the reset password API.

Once you add a user through the Users API, requests from that user can be authenticated.

curl -u eustace:secret-password http://localhost:9200/_cluster/health

To retrieve a native user, submit a GET request to the /_xpack/security/user/<username> endpoint:

GET /_xpack/security/user/jacknich

A successful call returns an array of users with the JSON representation of the user. Note that user passwords are not included.

{
  "jacknich": {  
    "username" : "jacknich",
    "roles" : [ "admin", "other_role1" ],
    "full_name" : "Jack Nicholson",
    "email" : "jacknich@example.com",
    "enabled": true,
    "metadata" : {
      "intelligence" : 7
    }
  }
}

If the user is not defined in the native realm, the request 404s.

You can specify multiple usernames as a comma-separated list:

GET /_xpack/security/user/jacknich,rdinero

or omit the username all together to retrieve all users:

GET /_xpack/security/user

To reset the password for a user, submit a PUT request to the /_xpack/security/user/<username>/_password endpoint:

PUT /_xpack/security/user/jacknich/_password
{
  "password" : "s3cr3t"
}

To disable a user, submit a PUT request to the /_xpack/security/user/<username>/_disable endpoint:

PUT /_xpack/security/user/jacknich/_disable

To enable a user, submit a PUT request to the /_xpack/security/user/<username>/_enable endpoint:

PUT /_xpack/security/user/jacknich/_enable

To delete a user, submit a DELETE request to the /_xpack/security/user/<username> endpoint:

DELETE /_xpack/security/user/jacknich

If the user is successfully deleted, the request returns {"found": true}. Otherwise, found is set to false.

{
  "found" : true
}