Create Role

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

Creates a new custom role within a workspace. Only CUSTOM roles can be created via this endpoint; OWNER roles are created automatically with the workspace.

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

Request Body

{
  "roleName": "Editor",
  "description": "Custom role with edit permissions"
}

Request Example

{
  "roleName": "Editor",
  "description": "Can edit content"
}

Success Response

Status: 201 Created

201 Created 201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2001",
  "message": "CREATED",
  "data": {
    "bizId": "role_abc123def456",
    "workspaceBizId": "WS_ROLE_TEST_001",
    "roleName": "Editor",
    "roleType": {
      "value": 10010902,
      "name": "CUSTOM",
      "code": "CUSTOM"
    },
    "description": "Custom role with edit permissions",
    "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 (null on creation, set via Set Role Permissions)
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"
}

Conflict 409

{
  "success": false,
  "code": "WORKSPACE.ROLE_NAME_EXISTS",
  "message": "A role with this name already exists in the workspace"
}

Notes

• Returns HTTP 201 with response code "2001" on success.
• Duplicate role names within the same workspace return 409 WORKSPACE.ROLE_NAME_EXISTS.
• Requires workspace:role:write permission.