IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Get roles API

edit

Get roles API

edit

Retrieves roles in the native realm.

Request

edit

GET /_xpack/security/role

GET /_xpack/security/role/<name>

Description

edit

For more information about the native realm, see Realms and Configuring a native realm.

Path Parameters

edit

name: (string) The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.

Authorization

edit

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

Examples

edit

The following example retrieves information about the my_admin_role role in the native realm:

GET /_xpack/security/role/my_admin_role

A successful call returns an array of roles with the JSON representation of the role. If the role is not defined in the native realm, the request returns 404.

{
  "my_admin_role": {
    "cluster" : [ "all" ],
    "indices" : [
      {
        "names" : [ "index1", "index2" ],
        "privileges" : [ "all" ],
        "field_security" : {
          "grant" : [ "title", "body" ]}
      }
    ],
    "applications" : [ ],
    "run_as" : [ "other_user" ],
    "metadata" : {
      "version" : 1
    },
    "transient_metadata": {
      "enabled": true
    }
  }
}

To retrieve all roles, omit the role name:

GET /_xpack/security/role

If single role is requested, that role is returned as the response. When requesting multiple roles, an object is returned holding the found roles, each keyed by the relevant role name.

« Get role mappings API Get token API »