WARNING: Version 5.5 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Clear Cache API Role Management APIs »

› › ›

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.

A username must be at least 1 character and no longer than 30 characters. The first character must be a letter (a-z or A-Z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9), or any of the following symbols @, -, . or $

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.

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
}

« Clear Cache API Role Management APIs »