WARNING: Version 6.2 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.

› › ›

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.

Request

GET /_xpack/security/user

GET /_xpack/security/user/<username>

DELETE /_xpack/security/user/<username>

POST /_xpack/security/user/<username>

PUT /_xpack/security/user/<username>

PUT /_xpack/security/user/<username>/_disable

PUT /_xpack/security/user/<username>/_enable

PUT /_xpack/security/user/<username>/_password

Description

You can use the PUT user API to create or 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.

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.

Path Parameters

username: (string) An identifier for the user. If you omit this parameter from a Get User API request, it retrieves information about all users.

Request Body

The following parameters can be specified in the body of a POST or PUT request and pertain to creating a user:

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

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

Examples

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

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 through the Users API, requests from that user can be authenticated. For example:

curl -u jacknich:j@rV1s 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

Omit the username 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
}

« Token Management APIs Watcher APIs »