List Roles

GET/web/v1/workspaces/{workspaceId}/roles JWT

Lists all roles defined in a workspace, including both OWNER and CUSTOM roles.

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

Success Response

Status: 200 OK

Returns an array of role objects.

Success 200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": [
    {
      "bizId": "ROLE_OWNER_TEST_001",
      "workspaceBizId": "WS_ROLE_TEST_001",
      "roleName": "Owner",
      "roleType": {
        "value": 10010901,
        "name": "OWNER",
        "code": "OWNER"
      },
      "description": "Workspace owner with full permissions",
      "permissionCodes": null,
      "createdAt": "2026-03-22T10:30:00Z",
      "updatedAt": "2026-03-22T10:30:00Z"
    },
    {
      "bizId": "ROLE_CUSTOM_TEST_001",
      "workspaceBizId": "WS_ROLE_TEST_001",
      "roleName": "Member",
      "roleType": {
        "value": 10010902,
        "name": "CUSTOM",
        "code": "CUSTOM"
      },
      "description": "Default member role",
      "permissionCodes": null,
      "createdAt": "2026-03-22T10:35:00Z",
      "updatedAt": "2026-03-22T10:35:00Z"
    }
  ]
}

Response Item Fields

Field	Type	Description
bizId	String	Unique role business ID
workspaceBizId	String	Parent workspace business ID
roleName	String	Role display name
roleType	Object	Role type enum: OWNER (10010901) or CUSTOM (10010902)
description	String	Role description
permissionCodes	Array	Permission codes (nullable in list view)
createdAt	String	ISO 8601 creation timestamp
updatedAt	String	ISO 8601 last update timestamp

Error Responses

Unauthorized 401

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

Notes

• Every workspace has at least one OWNER role (created automatically).
• Requires workspace:role:read permission.