Get Role

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

Retrieves a single workspace role by its ID, including its name, type, and description.

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

Success 200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "bizId": "ROLE_CUSTOM_TEST_001",
    "workspaceBizId": "WS_ROLE_TEST_001",
    "roleName": "Viewer",
    "roleType": {
      "value": 10010902,
      "name": "CUSTOM",
      "code": "CUSTOM"
    },
    "description": "Read-only viewer role",
    "permissionCodes": null,
    "createdAt": "2026-03-22T10:30:00Z",
    "updatedAt": "2026-03-22T10:30:00Z"
  }
}

Response 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 or CUSTOM
description	String	Role description
permissionCodes	Array	Permission codes assigned to this role (nullable)
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

• Requires workspace:role:read permission.