Delete Custom Role

Permanently delete a custom role from your tenant in the client Platform Custom Roles module.

Delete is blocked while users are still assigned this role (HTTP 409). Reassign those users first (Platform → Users → Update), then delete. Do not delete built-in system roles (isSystem: true).

Use Delete Custom Role when:

• An admin removes an unused custom role from Platform → Custom Roles.
• You are cleaning up obsolete desk or department roles after reassigning users.
• The role is custom (isSystem: false) and no longer needed.

Part of the client Platform Custom Roles module. If users still use this role slug, the API returns 409 Conflict until you reassign them.

On success, the role is removed. data may be null.

{
  "success": true,
  "message": "Role deleted successfully",
  "data": null,
  "error": null
}

Delete fails when the role is still assigned to users, the id is missing, or the token lacks admin access.

{
  "success": false,
  "message": "Cannot delete: 3 user(s) still assigned this role",
  "data": null,
  "error": null
}

{
  "success": false,
  "message": "Entity not found",
  "data": null,
  "error": "Entity not found"
}

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

• Before delete, list users with this role slug and reassign them via Platform → Users → Update.
• Hide Delete for isSystem roles in the Platform UI.
• Show the 409 message clearly so admins know how many users still use the role.
• Always send tenant headers with a client Bearer token over HTTPS.