API tạo phiên xác thực

API tạo bộ thông tin xác thực phiên để ứng dụng khách sử dụng khi gửi các yêu cầu cần đăng nhập vào workspace.

Khi nào cần dùng API này

Cogover hỗ trợ hai nhóm API với cơ chế xác thực khác nhau:

Nếu chức năng cần gọi chỉ có endpoint dạng /api/v{N} và không có endpoint tương ứng dạng /bapi/v{N}, ứng dụng có thể dùng POST /bapi/v1/auth-token để đổi API Key thành bộ thông tin xác thực phiên. Sau đó, dùng bộ thông tin này để gọi endpoint /api/v{N} giống như Web App chạy trên trình duyệt.

Luồng sử dụng:

1. Gọi POST /bapi/v1/auth-token bằng API Key.
2. Nhận và lưu HttpSessionId, XSRF-TOKEN và AuthToken.
3. Gửi ba giá trị dưới dạng cookie khi gọi /api/v{N}.
4. Gửi giá trị XSRF-TOKEN trong cả hai header x-csrf-token và x-xsrf-token.

Yêu cầu xác thực

Sử dụng API Key của workspace theo định dạng:

Authorization: Bearer {tokenId}-{secretToken}

API Key phải còn hiệu lực và có quyền truy cập workspace tương ứng.

Không đưa API Key vào URL, mã nguồn phía trình duyệt, log hoặc nội dung có thể được chia sẻ công khai.

Endpoint

POST /bapi/v1/auth-token

Request không yêu cầu dữ liệu đầu vào. Có thể gửi JSON rỗng {}.

Ví dụ cURL

curl --location --request POST 'https://{workspace-domain}/bapi/v1/auth-token' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{}'

Thay các giá trị sau:

• {workspace-domain}: tên miền dùng để truy cập workspace.
• {tokenId}-{secretToken}: API Key đầy đủ được cấp cho ứng dụng.

Response thành công

HTTP status: 200 OK

{
  "r": 0,
  "msg": "Success",
  "data": {
    "HttpSessionId": "c77c8ecb-af6f-4a49-ad02-32c7e5869295-yvxlf0ug",
    "HttpSessionExpiresAt": 1786672800,
    "XSRF-TOKEN": "2LHTC9RD8I19BAXJPWZOJC6ZJNSGMJVTDTJXK66R",
    "AuthToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AuthTokenExpiresAt": 1817694862
  },
  "workspaceId": "WSkdGop6AEvA9",
  "workspaceDomain": "example",
  "personnelId": "PER123"
}

Các trường response

Sử dụng thông tin phiên

Response thiết lập ba cookie HttpSessionId, XSRF-TOKEN và AuthToken. Với client hỗ trợ cookie tự động, hãy lưu và gửi lại các cookie này trong các request tiếp theo.

Với client tự quản lý cookie, gửi request cần xác thực theo ví dụ:

Cookie: HttpSessionId={HttpSessionId}; XSRF-TOKEN={XSRF-TOKEN}; AuthToken={AuthToken}
x-csrf-token: {XSRF-TOKEN}
x-xsrf-token: {XSRF-TOKEN}

Giá trị trong hai header x-csrf-token, x-xsrf-token phải giống nhau và phải bằng giá trị cookie XSRF-TOKEN.

Ví dụ gọi API /api/v{N} bằng phiên vừa tạo

curl --url 'https://{workspace-domain}/api/v1/accounts?limit=20&order=last_join_time&sort=desc&status=ACTIVE,INVITED' \
  --header 'accept: application/json, text/plain, */*' \
  --cookie 'HttpSessionId={HttpSessionId}; XSRF-TOKEN={XSRF-TOKEN}; AuthToken={AuthToken}' \
  --header 'x-csrf-token: {XSRF-TOKEN}' \
  --header 'x-xsrf-token: {XSRF-TOKEN}'

Trình duyệt sẽ tự gửi các cookie đã lưu tới đúng workspace. Mã JavaScript của Web App đọc cookie XSRF-TOKEN và đặt cùng giá trị vào hai header CSRF/XSRF trước khi gửi request.

Ứng dụng nên tạo lại phiên trước HttpSessionExpiresAt và không tiếp tục sử dụng AuthToken sau AuthTokenExpiresAt. Thời gian phiên có thể được gia hạn khi người dùng tiếp tục hoạt động; hãy ưu tiên giá trị mới nhất do API trả về nếu ứng dụng gọi lại endpoint này.

Ví dụ cURL lưu cookie tự động

# Tạo phiên và lưu cookie vào file cookies.txt
curl --location --request POST 'https://{workspace-domain}/bapi/v1/auth-token' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --cookie-jar cookies.txt \
  --data '{}'

Khi gọi API /api/v{N} tiếp theo, dùng --cookie cookies.txt và gửi giá trị XSRF-TOKEN trong cả hai header x-csrf-token và x-xsrf-token.

Lưu ý bảo mật

• Xem AuthToken, HttpSessionId và XSRF-TOKEN là thông tin nhạy cảm.
• Chỉ truyền các giá trị này qua HTTPS.
• Không ghi token vào log, URL, công cụ theo dõi lỗi hoặc nội dung hỗ trợ khách hàng.
• Không chia sẻ phiên giữa những người dùng hoặc thiết bị không tin cậy.

Mã lỗi

Response lỗi có dạng chung:

{
  "r": 100001,
  "msg": "Unauthorized: missing token"
}