API quản lý API Key

API này dùng để xem danh sách, tạo, cập nhật và xoá API Key trong một workspace.

API Key dùng để xác thực các ứng dụng tự động khi gọi public API. Mỗi key hoạt động dưới danh nghĩa người dùng được chọn tại accountId và bị giới hạn bởi quyền hiện tại của người dùng đó.

Bảo vệ secret: Credential đầy đủ chỉ được trả về một lần sau khi tạo tại data.secretToken. Hãy lưu an toàn ngay lúc đó. API danh sách không cho phép lấy lại secret.

Xác thực và phân quyền

Mọi request cần có:

Authorization: Bearer {tokenId}-{secretToken}
Content-Type: application/json

Người dùng gắn với credential đang gọi phải có quyền quản lý API Key tương ứng:

Workspace được xác định từ credential đang gọi. Không gửi workspace ID trong body.

Danh sách endpoint

Endpoint danh sách dùng POST nhưng chỉ đọc dữ liệu.

Quy ước HTTP status:

Thao tác chỉ thành công khi r = 0.

Các trường của API Key

secretToken không thuộc tài nguyên được trả về từ API danh sách. Trường này chỉ xuất hiện trong response tạo thành công.

1. Xem danh sách API Key

Endpoint: POST /bapi/v1/api-keys/list

Request body

Tất cả các trường đều không bắt buộc. Gửi {} để dùng giá trị mặc định.

{
  "page": 1,
  "limit": 50,
  "name": "integration",
  "isActive": true,
  "accountId": "AC8M3Q7D2K1P",
  "order": "created",
  "sort": "desc"
}

Với khoảng thời gian một phía, để trống phía còn lại. Ví dụ:

• "1780000000000-": lớn hơn hoặc bằng thời điểm bắt đầu.
• "-1790000000000": nhỏ hơn hoặc bằng thời điểm kết thúc.

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/api-keys/list' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "limit": 50,
    "isActive": true,
    "order": "created",
    "sort": "desc"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Success",
  "meta": {
    "total": 1,
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 50
  },
  "data": [
    {
      "id": "AT8M3Q7D2K1P",
      "name": "Order integration",
      "description": "Key used by the order synchronization service",
      "isActive": true,
      "expiresOn": 1786185511152,
      "accountId": "AC8M3Q7D2K1P",
      "created": 1783507200000,
      "createdBy": "PE7M2Q9D4K6RX",
      "createdByInfo": null,
      "accountIdInfo": null
    }
  ]
}

Response không bao giờ chứa secretToken có thể sử dụng được.

2. Tạo API Key

Endpoint: POST /bapi/v1/api-keys

Alias tương đương: POST /bapi/v1/api-keys/create.

Request body

{
  "name": "Order integration",
  "description": "Key used by the order synchronization service",
  "isActive": true,
  "expiresOn": 1786185511152,
  "accountId": "AC8M3Q7D2K1P"
}

Nên chọn tài khoản có quyền tối thiểu, chỉ đủ cho nghiệp vụ của integration.

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/api-keys' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Order integration",
    "description": "Key used by the order synchronization service",
    "isActive": true,
    "expiresOn": 1786185511152,
    "accountId": "AC8M3Q7D2K1P"
  }'

Response thành công (201)

{
  "r": 0,
  "msg": "Success",
  "data": {
    "id": "AT8M3Q7D2K1P",
    "secretToken": "AT8M3Q7D2K1P-<one-time-secret>"
  }
}

Hãy sao chép data.secretToken ngay khi nhận response. Không đưa secret vào source code, bộ nhớ trình duyệt, URL, ticket, tin nhắn hoặc log ứng dụng.

3. Cập nhật API Key

Endpoint: PUT /bapi/v1/api-keys/{apiKeyId}

ID trên URL là nguồn tin cậy. Nếu body có id, giá trị đó sẽ bị bỏ qua và thay bằng {apiKeyId}.

Request body

{
  "name": "Order integration",
  "description": "Temporarily disabled during maintenance",
  "isActive": false,
  "expiresOn": 1786185511152,
  "accountId": "AC8M3Q7D2K1P"
}

name, description, isActive và accountId chỉ thay đổi khi được gửi.

Luôn gửi expiresOn khi cập nhật. Nếu bỏ qua, phiên bản dịch vụ hiện tại sẽ đặt trường này thành 0 (không hết hạn). Gửi rõ 0 khi đó là kết quả mong muốn.

Thay đổi hoặc xoá thời hạn không làm lộ hay thay thế secret hiện tại. Để xoay vòng secret, hãy tạo key mới, cập nhật ứng dụng sử dụng key, sau đó vô hiệu hoá hoặc xoá key cũ.

Ví dụ cURL

curl --location --request PUT \
  'https://{workspace-domain}/bapi/v1/api-keys/AT8M3Q7D2K1P' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Temporarily disabled during maintenance",
    "isActive": false,
    "expiresOn": 1786185511152
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Success"
}

Dùng API danh sách với ID của key để xác minh trạng thái sau cập nhật.

4. Xoá API Key

Endpoint: POST /bapi/v1/api-keys/delete

Xoá sẽ thu hồi key vĩnh viễn và không thể hoàn tác. Nếu cần tạm dừng có thể khôi phục, hãy cập nhật isActive: false.

Request body

{
  "id": "AT8M3Q7D2K1P"
}

Ví dụ cURL

curl --location 'https://{workspace-domain}/bapi/v1/api-keys/delete' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "AT8M3Q7D2K1P"
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Success"
}

Nếu một key tự xoá chính nó, response xoá vẫn có thể thành công nhưng credential đó không thể xác thực các request tiếp theo.

Các lỗi thường gặp

Ví dụ:

{
  "r": 407,
  "msg": "NAME_EXIST"
}

Khuyến nghị bảo mật

• Dùng một key riêng cho mỗi integration và môi trường.
• Chọn tài khoản thực thi chuyên dụng với quyền tối thiểu.
• Đặt thời hạn và xoay vòng key định kỳ.
• Vô hiệu hoá ngay key bị nghi ngờ trước khi điều tra hoặc thay thế.
• Không để secret xuất hiện trong mã phía client hoặc log.
• Sau khi xoay vòng, xác minh key mới hoạt động trước khi xoá key cũ.