This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Bulk create or update roles API Create or update users API »

› › ›

Bulk delete roles API

edit

Bulk delete roles API

edit

Bulk deletes roles in the native realm.

Request

edit

DELETE /_security/role/

Prerequisites

edit

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

Description

edit

The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk delete roles API cannot delete roles that are defined in roles files.

Path parameters

edit

refresh: Optional setting of the refresh policy for the write request. Defaults to Immediate.

Request body

edit

The following parameters can be specified in the body of a DELETE request and pertain to deleting a set of roles:

names: (list) A list of role names to delete.

Examples

edit

The following example deletes a my_admin_role and my_user_role roles:

resp = client.security.bulk_delete_role(
    names=[
        "my_admin_role",
        "my_user_role"
    ],
)
print(resp)

const response = await client.security.bulkDeleteRole({
  names: ["my_admin_role", "my_user_role"],
});
console.log(response);

DELETE /_security/role
{
    "names": ["my_admin_role", "my_user_role"]
}

If the roles are successfully deleted, the request returns:

{
    "deleted": [
        "my_admin_role",
        "my_user_role"
    ]
}

If a role cannot be found, the not found roles are grouped under not_found:

resp = client.security.bulk_delete_role(
    names=[
        "my_admin_role",
        "not_an_existing_role"
    ],
)
print(resp)

const response = await client.security.bulkDeleteRole({
  names: ["my_admin_role", "not_an_existing_role"],
});
console.log(response);

DELETE /_security/role
{
    "names": ["my_admin_role", "not_an_existing_role"]
}

{
    "deleted": [
        "my_admin_role"
    ],
    "not_found": [
        "not_an_existing_role"
    ]
}

If a request fails or is invalid, the errors are grouped under errors:

resp = client.security.bulk_delete_role(
    names=[
        "my_admin_role",
        "superuser"
    ],
)
print(resp)

const response = await client.security.bulkDeleteRole({
  names: ["my_admin_role", "superuser"],
});
console.log(response);

DELETE /_security/role
{
    "names": ["my_admin_role", "superuser"]
}

{
    "deleted": [
        "my_admin_role"
    ],
    "errors": {
        "count": 1,
        "details": {
            "superuser": {
                "type": "illegal_argument_exception",
                "reason": "role [superuser] is reserved and cannot be deleted"
            }
        }
    }
}

« Bulk create or update roles API Create or update users API »