anchor.diff:  [[security-api-role-mapping]]
   === Role Mapping APIs
   
  -The Role Mapping API enables you to add, remove, and retrieve role-mappings.
  -To use this API, you must have at least the `manage_security` cluster privilege.
  +The Role Mapping API enables you to add, remove, and retrieve role mappings.
   
  -NOTE: The API requires that each role-mapping have a distinct name. The name is
  +==== Request
  +
  +`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>`
  +
  +==== Description
  +
  +NOTE: 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
  +{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
  +
  +==== Path Parameters
  +
  +`name`::
  + (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.
  +
  +`metadata`::
  +(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.
  +
  +
  +==== Authorization
  +
  +To use this API, you must have at least the `manage_security` cluster privilege.
  +
  +
  +==== Examples
  +
   [[security-api-put-role-mapping]]
  -To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
  +To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
   endpoint:
   
   [source,js]
  
positive.code: <1> When an existing mapping is updated, `created` is set to false.
  
  [[security-api-get-role-mapping]]
  To retrieve a role-mapping, issue a GET request to the
  `/_xpack/security/role_mapping/<name>` endpoint:
  
  [source,js]
  
negative.code: // TEST[continued]
  
  [[security-api-delete-role-mapping]]
  To delete a role mapping, submit a DELETE request to the
  `/_xpack/security/role_mapping/<name>` endpoint:
  
  [source,js]
  