User Login Token
User Login Token thường hay được gọi là "JWT Token", có được do từng phiên đăng nhập của nhân viên. Các request sử dụng Token này sẽ đại diện cho một nhân viên tương ứng khi đăng nhập, nên Token này chỉ có thể truy cập vào các API mà nhân viên này được phép truy cập.
Mỗi Token gắn với một công ty (công ty được chọn lúc đăng nhập). Nếu tài khoản thuộc nhiều công ty, muốn làm việc với công ty khác thì gọi Đổi công ty đang làm việc để lấy Token mới.
User Login Token có hạn sử dụng và theo phiên đăng nhập của nhân viên. Nếu nhân viên đăng xuất khỏi hệ thống thì Token này sẽ hết hạn, hoặc tự động hết hạn vào cuối ngày thứ 14 kể từ lúc đăng nhập (23:59:59 giờ Việt Nam). Trước khi hết hạn, có thể dùng refresh_token để làm mới Token. Một phiên đăng nhập dùng tối đa 30 ngày kể từ lúc đăng nhập (làm mới không kéo dài quá mốc này, mã lỗi error_session_max_age); sau đó phải đăng nhập lại.
Cách lấy User Login Token
Cách 1: Gọi API đăng nhập
Gọi API Đăng nhập (POST /v1/users/authenticateinit để lấy danh sách công ty, sau đó POST /v1/users/authenticatefinish với company_id đã chọn). Giá trị jwt trong response chính là User Login Token.
curl -X POST https://api.hubport.vn/v1/users/authenticatefinish \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "<PASSWORD>", "company_id": 10311}'Cách 2: Lấy từ trang quản trị đang đăng nhập
- Đăng nhập vào trang quản trị Hubport
- Lấy JWT Token từ localStorage, key "MAIN::LoginAccount", thuộc tính "state.account.jwt"
- Kết nối với API sử dụng JWT Token này
Token lấy theo cách 2 sẽ mất hiệu lực khi bạn đăng xuất hoặc đổi sang công ty khác trên trang quản trị.
Cách kết nối dùng User Login Token
Kết nối với API sử dụng JWT Token này bằng cách gửi Header có tên là "Authorization" và có giá trị theo định dạng "JWTToken". Ví dụ nếu JWT Token của bạn là "123" thì các request của bạn gửi lên server phải có thêm header "Authorization" có giá trị là "123".
Authorization: <JWT>Không dùng tiền tố Bearer
Gửi nguyên giá trị Token, không thêm Bearer phía trước. Header dạng Authorization: Bearer <JWT> sẽ bị từ chối với lỗi error_jwt_hash_not_found.
Token không được truyền trên query string. Từ tháng 10/2026, request chỉ gửi Token qua tham số __jwtAuthorization trên URL bị từ chối với lỗi error_jwt_query_not_allowed (HTTP 401), vì URL bị lưu lại trong lịch sử trình duyệt, log của proxy và header Referer. Mọi method (kể cả GET) phải gửi header Authorization. Quy tắc này áp dụng cho cả API Key dạng key:secret.
Lỗi xác thực thường gặp
| HTTP | Code | Mô tả |
|---|---|---|
| 401 | error_jwt_is_required | Thiếu Token ở API cần xác thực |
| 401 | error_jwt_query_not_allowed | Token gửi trên query string (__jwtAuthorization); hãy gửi header Authorization |
| 401 | error_jwt_hash_not_found | Token không tồn tại hoặc sai định dạng (ví dụ có tiền tố Bearer) |
| 400 | error_jwt_blacklisted | Token đã bị vô hiệu (đã đăng xuất, đổi công ty, bị thu hồi phiên) |
| 400 | error_jwt_expired | Token đã hết hạn |
Xem thêm HTTP Status Code.