Bulk delete roles Generally available; Added in 8.15.0

DELETE /_security/role

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. ##Required authorization

  • Cluster privileges: manage_security

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

  • names array[string] Required

    An array of role names to delete

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • deleted array[string]

      Array of deleted roles

    • not_found array[string]

      Array of roles that could not be found

    • errors object
      Hide errors attributes Show errors attributes object
      • count number Required

        The number of errors

      • details object Required

        Details about the errors, keyed by role name

        Hide details attribute Show details attribute object
        • * object
          Hide * attributes Show * attributes object
          • type string Required

            The type of error

          • reason string | null

            A human-readable explanation of the error, in English.

            One of:
            string-1 string string-2 string | null
          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object
          • root_cause array[object]
          • suppressed array[object]
DELETE /_security/role 
DELETE /_security/role
{
    "names": ["my_admin_role", "my_user_role"]
}
curl \
 --request DELETE 'http://api.example.com/_security/role' \
 --header "Content-Type: application/json" \
 --data '"{\n    \"names\": [\"my_admin_role\", \"my_user_role\"]\n}"'
Request examples
An example body for a `DELETE /_security/role` request. 
{
    "names": ["my_admin_role", "my_user_role"]
}
Run DELETE /_security/role` to delete `my_admin_role` and `my_user_role` roles. 
{
  "names": ["my_admin_role", "my_user_role"]
}
Response examples (200)
A successful response from `DELETE /_security/role`. 
{
  "deleted": [
      "my_admin_role",
      "my_user_role"
  ]
}
A partially successful response from `DELETE /_security/role`. If a role cannot be found, it appears in the `not_found` list in the response. 
{
  "deleted": [
      "my_admin_role"
  ],
  "not_found": [
      "not_an_existing_role"
  ]
}
A partially successful response from `DELETE /_security/role`. If part of a request fails or is invalid, the response includes `errors`. 
{
  "deleted": [
      "my_admin_role"
  ],
  "errors": {
      "count": 1,
      "details": {
          "superuser": {
              "type": "illegal_argument_exception",
              "reason": "role [superuser] is reserved and cannot be deleted"
          }
      }
  }
}

Documentation preview

This is a preview of your version @2025-06-09 which is not yet released.

View current documentation