Role Mapping APIs

The Role Mapping API enables you to add, remove, and retrieve role mappings.


GET /_xpack/security/role_mapping

GET /_xpack/security/role_mapping/<name>

DELETE /_xpack/security/role_mapping/<name>

POST /_xpack/security/role_mapping/<name>

PUT /_xpack/security/role_mapping/<name>



The API requires that each role mapping have a distinct name. The name is used solely as an identifier to facilitate interaction via the API, and does not affect the behavior of the mapping in any way.

For more information, see Mapping Users and Groups to Roles.

Path Parameters

(string) The distinct name that identifies the role mapping. If you do not specify this parameter, the Get Role Mappings API returns information about all role mappings.

Request Body

The following parameters can be specified in the body of a PUT or POST request and pertain to adding a role mapping:

enabled (required)
(boolean) Mappings that have enabled set to false are ignored when role mapping is performed.
(object) Additional metadata that helps define which roles are assigned to each user. Within the metadata object, keys beginning with _ are reserved for system usage.
roles (required)
(list) A list of roles that are granted to the users that match the role-mapping rules.
rules (required)
(object) The rules that determine which users should be matched by the mapping. A rule is a logical condition that is expressed by using a JSON DSL.


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


To add a role mapping, submit a PUT or POST request to the /_xpack/security/role_mapping/<name> endpoint:

POST /_xpack/security/role_mapping/administrators
  "roles": [ "user", "admin" ],
  "enabled": true, 
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  "metadata" : { 
    "version" : 1

Mappings that have enabled set to false will be ignored when role mapping is performed.

Metadata is optional

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

  "role_mapping" : {
    "created" : true 

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

To retrieve a role mapping, issue a GET request to the /_xpack/security/role_mapping/<name> endpoint:

GET /_xpack/security/role_mapping/administrators

A successful call retrieves an object, where the keys are the names of the request mappings, and the values are the JSON representation of those mappings. If there is no mapping with the requested name, the response will have status code 404.

  "administrators" : {
    "enabled" : true,
    "roles" : [
    "rules" : {
      "field" : {
        "username" : [
    "metadata" : {
      "version" : 1

You can specify multiple mapping names as a comma-separated list. To retrieve all mappings, omit the name entirely.

# Retrieve mappings "m1", "m2", and "administrators"
GET /_xpack/security/role_mapping/m1,m2,administrators

# Retrieve all mappings
GET /_xpack/security/role_mapping

To delete a role mapping, submit a DELETE request to the /_xpack/security/role_mapping/<name> endpoint:

DELETE /_xpack/security/role_mapping/administrators

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

  "found" : true