Roles

5/8/2026

blog.summarize

blog.share_blog

Roles API

API dùng để xem danh sách, xem chi tiết, tạo, cập nhật, xóa, gán và loại vai trò khỏi người dùng trong workspace.

Xác thực

Tất cả request yêu cầu header:

Authorization: Bearer {tokenId}-{secretToken}

Với request có JSON body, gửi thêm:

Content-Type: application/json

1. Xem danh sách vai trò

Endpoint: POST /bapi/v1/roles/list

Request Body

{
  "page": 1,
  "limit": 20,
  "name": "Quản lý",
  "nameOperator": "LIKE",
  "roleType": 2,
  "order": "updated",
  "sort": "desc"
}

Trường	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Số trang. Mặc định: `1`
`limit`	Integer	Không	Số vai trò tối đa mỗi trang. Mặc định: `20`
`id`	String	Không	Lọc theo ID vai trò
`idOperator`	String	Không	Toán tử cho `id`
`name`	String	Không	Lọc theo tên vai trò
`nameOperator`	String	Không	Toán tử cho `name`; thường dùng `LIKE`
`description`	String	Không	Lọc theo mô tả
`descriptionOperator`	String	Không	Toán tử cho `description`; thường dùng `LIKE`
`roleType`	Integer/String	Không	Loại vai trò: `1` = vai trò có sẵn, `2` = vai trò tùy chỉnh. Với nhiều giá trị, dùng chuỗi phân tách bằng dấu phẩy
`roleTypeOperator`	String	Không	Toán tử cho `roleType`; dùng `IN` khi truyền nhiều giá trị
`isSuperAdmin`	Boolean/Integer	Không	Lọc vai trò quản trị cao nhất (`true`/`false` hoặc `1`/`0`)
`isSuperAdminOperator`	String	Không	Toán tử cho `isSuperAdmin`
`createdBy`	String	Không	ID người tạo; nhiều ID được phân tách bằng dấu phẩy khi dùng `IN`
`createdByOperator`	String	Không	Toán tử cho `createdBy`
`updatedBy`	String	Không	ID người cập nhật gần nhất; nhiều ID được phân tách bằng dấu phẩy khi dùng `IN`
`updatedByOperator`	String	Không	Toán tử cho `updatedBy`
`createdStart`	Long	Không	Thời điểm tạo từ, timestamp mili giây
`createdEnd`	Long	Không	Thời điểm tạo đến, timestamp mili giây
`updatedStart`	Long	Không	Thời điểm cập nhật từ, timestamp mili giây
`updatedEnd`	Long	Không	Thời điểm cập nhật đến, timestamp mili giây
`created`	Long/String	Không	Giá trị tạo dùng với `createdOperator`
`createdOperator`	String	Không	Toán tử cho `created`
`updated`	Long/String	Không	Giá trị cập nhật dùng với `updatedOperator`
`updatedOperator`	String	Không	Toán tử cho `updated`
`order`	String	Không	Trường sắp xếp: `id`, `name`, `description`, `roleType`, `isSuperAdmin`, `created`, `updated`, `createdBy` hoặc `updatedBy`. Mặc định: `updated`
`sort`	String	Không	Chiều sắp xếp: `asc` hoặc `desc`. Mặc định: `desc`

Các toán tử được hỗ trợ: =, !=, >, >=, <, <=, IN, NOT IN, LIKE, NOT LIKE. IN và NOT IN nhận chuỗi giá trị phân tách bằng dấu phẩy.

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles/list' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "limit": 20,
    "name": "Quản lý",
    "nameOperator": "LIKE",
    "roleType": 2,
    "order": "updated",
    "sort": "desc"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": [
    {
      "id": "RO6P2N1K9X4A",
      "workspaceId": "WS8M3Q7D2K1P",
      "name": "Quản lý bán hàng",
      "description": "Quản lý người dùng và dữ liệu bán hàng",
      "roleType": 2,
      "isSuperAdmin": 0,
      "canAssign": true,
      "created": 1785888000000,
      "updated": 1785891600000,
      "createdBy": {
        "id": "USR4J8H2Q7MN",
        "fullName": "Nguyễn Văn An"
      },
      "updatedBy": {
        "id": "USR4J8H2Q7MN",
        "fullName": "Nguyễn Văn An"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "currentPage": 1
  },
  "requestId": "d7a2281c-000120417-88405328-f86b-41f6-8e13-0bdd86b34a23"
}

permissions không được trả về trong API danh sách. Dùng API xem chi tiết để lấy cấu hình quyền của một vai trò.

2. Xem chi tiết vai trò

Endpoint: POST /bapi/v1/roles/view

Request Body

{
  "id": "RO6P2N1K9X4A"
}

Trường	Kiểu	Bắt buộc	Mô tả
`id`	String	Có	ID vai trò cần lấy

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles/view' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "RO6P2N1K9X4A"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": {
    "id": "RO6P2N1K9X4A",
    "workspaceId": "WS8M3Q7D2K1P",
    "name": "Quản lý bán hàng",
    "description": "Quản lý người dùng và dữ liệu bán hàng",
    "roleType": 2,
    "isSuperAdmin": 0,
    "canAssign": null,
    "permissions": [
      {
        "id": "PERM7A3F9K2M",
        "roleId": "RO6P2N1K9X4A",
        "functionCode": "workspace_account",
        "actions": ["view", "create", "edit"],
        "groupSlug": "object",
        "parent": "",
        "valueOption": 3,
        "values": [],
        "created": 1785888000000,
        "updated": 1785891600000
      }
    ],
    "created": 1785888000000,
    "updated": 1785891600000
  },
  "requestId": "d7a2281c-000120417-9a853210-32bd-4855-9d8a-c234cc0b5516"
}

canAssign trong response chi tiết có thể là null. Khi cần kiểm tra khả năng gán vai trò, sử dụng giá trị canAssign từ API danh sách.

3. Tạo vai trò

Endpoint: POST /bapi/v1/roles

Request Body

{
  "name": "Quản lý bán hàng",
  "description": "Quản lý người dùng và dữ liệu bán hàng",
  "permissions": [
    {
      "functionCode": "workspace_account",
      "actions": ["view", "create", "edit"],
      "groupSlug": "object",
      "values": [],
      "valueOption": 3
    }
  ]
}

Trường	Kiểu	Bắt buộc	Mô tả
`name`	String	Có	Tên vai trò, từ 1 đến 100 ký tự và không trùng với vai trò khác trong workspace
`description`	String/null	Không	Mô tả, tối đa 500 ký tự
`permissions`	Array	Có	Danh sách quyền, phải có ít nhất một phần tử. Gửi mảng rỗng sẽ trả lỗi validation

Mỗi phần tử trong permissions có cấu trúc:

Trường	Kiểu	Bắt buộc	Mô tả
`functionCode`	String	Có	Mã tính năng được cấp quyền, ví dụ `workspace_account`
`actions`	Array[String]	Có	Các thao tác hợp lệ của tính năng, ví dụ `view`, `create`, `edit`, `delete`
`groupSlug`	String/null	Không	Nhóm dữ liệu của quyền, tối đa 100 ký tự; thường là `object`
`parent`	String/null	Không	Mã quyền cha nếu có, tối đa 15 ký tự
`values`	Array[Object]/null	Không	Phạm vi dữ liệu áp dụng; mỗi phần tử gồm `id` và `slug` tùy chọn
`valueOption`	Integer/null	Không	Cách áp dụng `values`: `1` = chỉ các giá trị đã chọn, `2` = tất cả trừ các giá trị đã chọn, `3` = tất cả

functionCode và actions phải là các mã được workspace hỗ trợ. Khi valueOption = 3, gửi values: [].

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Quản lý bán hàng",
    "description": "Quản lý người dùng và dữ liệu bán hàng",
    "permissions": [
      {
        "functionCode": "workspace_account",
        "actions": ["view", "create", "edit"],
        "groupSlug": "object",
        "values": [],
        "valueOption": 3
      }
    ]
  }'

Response thành công (201)

data chứa vai trò vừa tạo cùng các trường do hệ thống sinh như id, workspaceId, roleType, isSuperAdmin, created và updated. Gọi API xem chi tiết với ID vừa tạo để lấy danh sách permissions đã lưu.

4. Cập nhật vai trò

Endpoint: PUT /bapi/v1/roles/{role_id}

Path Parameters

Trường	Kiểu	Bắt buộc	Mô tả
`role_id`	String	Có	ID vai trò cần cập nhật

Request Body

{
  "name": "Quản lý bán hàng cấp cao",
  "description": "Mô tả đã cập nhật",
  "permissions": [
    {
      "id": "PERM7A3F9K2M",
      "functionCode": "workspace_account",
      "actions": ["view", "create", "edit", "delete"],
      "groupSlug": "object",
      "values": [],
      "valueOption": 3
    }
  ]
}

name là tùy chọn. Luôn gửi description để giữ đúng giá trị hiện tại (null dùng để xóa mô tả) và luôn gửi permissions; dùng [] nếu không thay đổi quyền.

Quy tắc cập nhật từng phần tử quyền:

Có id: cập nhật quyền hiện có và thay thế toàn bộ values của quyền đó.
Không có id: thêm quyền mới.
Có id và status: 0: xóa quyền đó.
Không gửi một quyền hiện có trong mảng không đồng nghĩa với xóa quyền; muốn xóa phải dùng status: 0.

Ví dụ xóa một quyền trong cùng request cập nhật:

{
  "id": "PERM4D8Q1T6N",
  "functionCode": "workspace_account",
  "actions": ["view"],
  "status": 0
}

Ví dụ cURL

curl --location --request PUT 'https://{workspace-domain}/bapi/v1/roles/RO6P2N1K9X4A' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Quản lý bán hàng cấp cao",
    "description": "Mô tả đã cập nhật",
    "permissions": [
      {
        "id": "PERM7A3F9K2M",
        "functionCode": "workspace_account",
        "actions": ["view", "create", "edit", "delete"],
        "groupSlug": "object",
        "values": [],
        "valueOption": 3
      }
    ]
  }'

Response thành công (200)

Response update có thể phản ánh dữ liệu trước thời điểm cập nhật. Ví dụ, dù request phía trên gửi tên và mô tả mới, response có thể là:

{
  "r": 0,
  "msg": "Successful",
  "data": {
    "id": "RO6P2N1K9X4A",
    "name": "Quản lý bán hàng",
    "description": "Quản lý người dùng và dữ liệu bán hàng",
    "roleType": 2,
    "isSuperAdmin": 0,
    "canAssign": null,
    "permissions": null
  },
  "requestId": "d7a2281c-000121322-e29c31bb-d212-4ff3-83b3-07b305798afa"
}

data trong response update có thể vẫn chứa tên và mô tả trước khi cập nhật, đồng thời có thể không kèm permissions. Không dùng object này để xác nhận trạng thái mới; luôn gọi API xem chi tiết với role_id sau khi cập nhật thành công.

5. Xóa vai trò

Endpoint: POST /bapi/v1/roles/delete

Request Body

{
  "ids": ["RO6P2N1K9X4A"]
}

Trường	Kiểu	Bắt buộc	Mô tả
`ids`	Array[String]	Có	Danh sách ID vai trò cần xóa

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles/delete' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": ["RO6P2N1K9X4A"]
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": 1,
  "requestId": "d7a2281c-000121322-7591fc72-cbbb-4d20-9a6b-cad9c5526ca4"
}

Giá trị data là kết quả của thao tác xóa và không nhất thiết bằng số ID đã gửi. Chỉ xóa các vai trò mà token hiện tại được phép quản lý.

6. Gán vai trò cho người dùng

Endpoint: POST /bapi/v1/roles/addAccount

API gán một vai trò cho một người dùng. Thao tác này chỉ thêm vai trò được chỉ định và không làm mất các vai trò khác mà người dùng đang có.

Request Body

{
  "roleId": "RO6P2N1K9X4A",
  "userId": "USR4J8H2Q7MN"
}

Trường	Kiểu	Bắt buộc	Mô tả
`roleId`	String	Có	ID vai trò cần gán. Có thể lấy từ API danh sách hoặc chi tiết vai trò
`userId`	String	Có	ID người dùng (`data.id`) trả về từ Users API

Người dùng phải có trạng thái ACTIVE hoặc INVITED. Token hiện tại phải có quyền gán vai trò này; kiểm tra vai trò có canAssign: true trong API danh sách.

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles/addAccount' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleId": "RO6P2N1K9X4A",
    "userId": "USR4J8H2Q7MN"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": true,
  "requestId": "d7a2281c-000121322-2d9fdf43-d348-4557-a0ef-7e4cb0593365"
}

Nếu người dùng đã có vai trò này, API vẫn trả về thành công và không tạo bản ghi trùng lặp.

Các lỗi phổ biến gồm không tìm thấy vai trò, không tìm thấy người dùng hợp lệ hoặc token hiện tại không được phép gán vai trò này.

7. Loại vai trò khỏi người dùng

Endpoint: POST /bapi/v1/roles/removeAccount

API loại một vai trò khỏi một người dùng. Thao tác này chỉ loại vai trò được chỉ định và không ảnh hưởng đến các vai trò khác của người dùng.

Request Body

{
  "roleId": "RO6P2N1K9X4A",
  "userId": "USR4J8H2Q7MN"
}

Trường	Kiểu	Bắt buộc	Mô tả
`roleId`	String	Có	ID vai trò cần loại khỏi người dùng
`userId`	String	Có	ID người dùng (`data.id`) trả về từ Users API

Token hiện tại phải có quyền gán/loại vai trò này. Không thể loại vai trò quản trị cao nhất khỏi người dùng cuối cùng đang đảm nhiệm vai trò đó.

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/roles/removeAccount' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleId": "RO6P2N1K9X4A",
    "userId": "USR4J8H2Q7MN"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Successful",
  "data": 1,
  "requestId": "d7a2281c-000121322-141ab82e-551f-4698-a165-31a44ba194c7"
}

Thao tác này không có tính idempotent. Nếu người dùng không có vai trò được chỉ định, API trả về lỗi với meta.accounts = "accounts_not_in_current_role".

Các lỗi phổ biến khác gồm không tìm thấy người dùng, token hiện tại không được phép loại vai trò hoặc thao tác sẽ làm workspace không còn người quản trị cao nhất.

Các trường của role resource

Trường	Kiểu	Mô tả
`id`	String	ID vai trò
`workspaceId`	String	ID workspace
`name`	String	Tên vai trò
`description`	String/null	Mô tả vai trò
`roleType`	Integer	`1` = vai trò có sẵn, `2` = vai trò tùy chỉnh
`isSuperAdmin`	Integer	`1` nếu là vai trò quản trị cao nhất, ngược lại là `0`
`canAssign`	Boolean/null	Ở API danh sách, cho biết token hiện tại có thể gán vai trò này hay không; API chi tiết có thể trả `null`
`permissions`	Array	Danh sách quyền; chỉ có trong response chi tiết
`created`	Long	Thời điểm tạo, timestamp mili giây
`updated`	Long	Thời điểm cập nhật gần nhất, timestamp mili giây
`createdBy`	Object/String/null	Thông tin tóm tắt người tạo
`updatedBy`	Object/String/null	Thông tin tóm tắt người cập nhật gần nhất

Quy ước response và lỗi

HTTP Status	Ý nghĩa
`200`	Xem danh sách, xem chi tiết, cập nhật hoặc xóa thành công
`201`	Tạo vai trò thành công
`400`	Lỗi nghiệp vụ hoặc validation (`r != 0`); chi tiết thường nằm trong `meta`
`401`	Bearer token bị thiếu, sai, hết hạn hoặc không hoạt động
`429`	Vượt giới hạn số lượng request
`500`	Lỗi không mong muốn

Các lỗi phổ biến gồm tên vai trò đã tồn tại (meta.name = "name_exist"), mã quyền/thao tác không hợp lệ và không tìm thấy vai trò.

Ghi chú

ID vai trò và phạm vi quyền thuộc từng workspace.
Request và response của Roles API sử dụng tên trường dạng camelCase.
Các timestamp dùng đơn vị mili giây.

blog.blogs_related

Roles

Roles API

Xác thực

1. Xem danh sách vai trò

Request Body

Ví dụ cURL

Response thành công (200)

2. Xem chi tiết vai trò

Request Body

Ví dụ cURL

Response thành công (200)

3. Tạo vai trò

Request Body

Ví dụ cURL

Response thành công (201)

4. Cập nhật vai trò

Path Parameters

Request Body

Ví dụ cURL

Response thành công (200)

5. Xóa vai trò

Request Body

Ví dụ cURL

Response thành công (200)

6. Gán vai trò cho người dùng

Request Body

Ví dụ cURL

Response thành công (200)

7. Loại vai trò khỏi người dùng

Request Body

Ví dụ cURL

Response thành công (200)

Các trường của role resource

Quy ước response và lỗi

Ghi chú

Số hóa và tự động hóa hoàn toàn công tác vận hành và quản trị doanh nghiệp với Cogover!