Docs
X-Pack for the Elastic Stack [5.1] » X-Pack APIs » Security APIs » Role Management APIs
«  User Management APIs     Watcher APIs  »

Role Management APIs

The Roles API enables you to add, remove, and retrieve roles in the native realm. To use this API, you must have at least the manage_security cluster privilege.

Note

The Roles API is now the preferred way to manage roles.

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

POST /_xpack/security/role/my_admin_role
{
  "cluster": ["all"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["all"],
      "field_security" : { // optional
        "grant" : [ "title", "body" ]
      },
      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
    }
  ],
  "run_as": [ "other_user" ], // optional
  "metadata" : { // optional
    "version" : 1
  }
}

The name, cluster, and indices fields are required at the top-level. Within the indices array, the names and privileges fields are required. Within the metadata object, keys beginning with _ are reserved for system usage.

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

{
  "role": {
    "created": true 
  }
}

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

To retrieve a role from the native Security realm, issue a GET request to the /_xpack/security/role/<rolename> endpoint:

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 404s.

{
  "my_admin_role": {
    "cluster" : [ "all" ],
    "indices" : [ {
      "names" : [ "index1", "index2" ],
      "privileges" : [ "all" ],
      "field_security" : {
        "grant" : [ "title", "body" ]
      },
      "query" : "{\"match\": {\"title\": \"foo\"}}"
    } ],
    "run_as" : [ "other_user" ],
    "metadata" : {
      "version" : 1
    }
  }
}

You can specify multiple roles as a comma-separated list. To retrieve all roles, omit the role name.

# Retrieve roles "r1", "r2", and "my_admin_role"
GET /_xpack/security/role/r1,r2,my_admin_role

# Retrieve all roles
GET /_xpack/security/role

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

DELETE /_xpack/security/role/my_admin_role

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

{
  "found" : true
}

The Clear Roles Cache API evicts roles from the native role cache. To clear the cache for a role, submit a POST request /_xpack/security/role/<rolename>/_clear_cache endpoint:

POST /_xpack/security/role/my_admin_role/_clear_cache
«  User Management APIs     Watcher APIs  »