elasticsearch/docs/reference/rest-api/security/bulk-delete-roles.asciidoc

[role="xpack"]
[[security-api-bulk-delete-role]]
=== Bulk delete roles API
++++
<titleabbrev>Bulk delete roles API</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

Bulk deletes roles in the native realm.

[[security-api-bulk-delete-role-request]]
==== {api-request-title}

`DELETE /_security/role/`

[[security-api-bulk-delete-role-prereqs]]
==== {api-prereq-title}

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

[[security-api-bulk-delete-role-desc]]
==== {api-description-title}

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

[[security-api-bulk-delete-role-path-params]]
==== {api-path-parms-title}

`refresh`::
Optional setting of the {ref}/docs-refresh.html[refresh policy] for the write request. Defaults to Immediate.

[[security-api-bulk-delete-role-request-body]]
==== {api-request-body-title}

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.

[[security-bulk-api-delete-role-example]]
==== {api-examples-title}
The following example deletes a `my_admin_role` and `my_user_role` roles:

[source,console]
--------------------------------------------------
DELETE /_security/role
{
    "names": ["my_admin_role", "my_user_role"]
}
--------------------------------------------------
// TEST[setup:admin_role,user_role]

If the roles are successfully deleted, the request returns:

[source,console-result]
--------------------------------------------------
{
    "deleted": [
        "my_admin_role",
        "my_user_role"
    ]
}
--------------------------------------------------

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

[source,console]
--------------------------------------------------
DELETE /_security/role
{
    "names": ["my_admin_role", "not_an_existing_role"]
}
--------------------------------------------------
// TEST[setup:admin_role]

[source,console-result]
--------------------------------------------------
{
    "deleted": [
        "my_admin_role"
    ],
    "not_found": [
        "not_an_existing_role"
    ]
}
--------------------------------------------------

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

[source,console]
--------------------------------------------------
DELETE /_security/role
{
    "names": ["my_admin_role", "superuser"]
}
--------------------------------------------------
// TEST[setup:admin_role]


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