Delete Role

POST/web/v1/system/roles/delete JWT

Required Gateway Headers

All API requests require gateway headers. See Required Headers for the complete list. In local/test environments, you must also include Cloudflare simulation headers (CF-Connecting-IP, Cf-Ray, cf-ipcountry).

Deletes a custom workspace role. The role must have no members assigned.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token
X-Workspace-Id		Target workspace ID

Request Parameters

Name	Type	Required	In	Description
workspaceId	String	Required	path	Business ID of the workspace
roleId	String	Required	path	Business ID of the role

Success Response

Status: 200 OK

200 OK 200

{
  "version": "2.0.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": null
}

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Conflict 409

{
  "success": false,
  "code": "WORKSPACE.OWNER_ROLE_PROTECTED",
  "message": "OWNER role cannot be deleted"
}

Conflict 409

{
  "success": false,
  "code": "WORKSPACE.ROLE_IN_USE",
  "message": "Cannot delete a role that still has members assigned"
}

Notes

• Returns HTTP 200 OK with {"success":true, "data":null} on success.
• OWNER roles cannot be deleted (409 WORKSPACE.OWNER_ROLE_PROTECTED).
• Roles with active members cannot be deleted (409 WORKSPACE.ROLE_IN_USE). Reassign members first via Change Member Role.
• Requires workspace:role:write permission.
• When a role is soft-deleted, its name is internally suffixed with _deleted_{timestamp} for database audit purposes. This is transparent to clients — the role simply disappears from listings.