HRMNhân viên
Làm mới Token
Lấy JWT Token mới bằng refresh token, không cần đăng nhập lại.
JWT Token hết hạn vào cuối ngày thứ 14 kể từ lúc tạo. Trước khi hết hạn, dùng refresh_token (nhận được khi đăng nhập hoặc đổi công ty) để lấy JWT Token mới với thời hạn mới. Phiên đăng nhập và công ty đang làm việc được giữ nguyên.
Endpoint
POST /v1/usersessions/refreshtoken
Headers
| Tên | Giá trị | Bắt buộc | Mô tả |
|---|---|---|---|
Content-Type | application/json | Có | |
Authorization | <JWT> | Không | Không cần nếu gửi jwt trong body. Nếu gửi thì JWT phải còn hiệu lực, nên khi JWT đã hết hạn hãy gửi jwt trong body và bỏ header này |
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
refresh_token | string | Có | Refresh token hiện tại của phiên |
jwt | string | Có (nếu không gửi header Authorization) | JWT Token hiện tại của phiên (giá trị jwt nhận lúc đăng nhập / lần làm mới gần nhất) |
Response Schema
HTTP 200 - JSON Object
{
"jwt": "fedcba9876543210fedcba9876543210",
"refresh_token": "b2c3d4e5f6a7...",
"date_expired": 1641920399
}| Field | Kiểu | Mô tả |
|---|---|---|
jwt | string | JWT Token mới |
refresh_token | string | Refresh token mới. Refresh token cũ không dùng lại được |
date_expired | int | Thời điểm hết hạn của JWT mới (UNIX timestamp) |
Workflow & Logic
- Mỗi refresh token chỉ dùng một lần: mỗi lần làm mới, cả JWT lẫn refresh token đều được thay. Lưu cặp mới ngay.
- Hai request làm mới cùng lúc bằng cùng một refresh token: chỉ một request thành công, request kia nhận
error_refresh_token_invalid. - Gửi lại refresh token cũ (đã được thay) sau hơn 30 giây được coi là token bị lộ: cả phiên bị thu hồi (
error_refresh_token_reused), phải đăng nhập lại. - JWT cũ vẫn dùng được thêm khoảng 5 phút sau khi làm mới, để các request đang chạy không bị lỗi.
- Làm mới được tới thời điểm
date_expiredcủa phiên. Quá hạn, hoặc phiên đã bị đăng xuất / thu hồi, thì phải đăng nhập lại; mã lỗi cho biết lý do. - Thời hạn tối đa của phiên: 30 ngày (mặc định) kể từ lần đăng nhập (đăng nhập bằng mật khẩu; đổi công ty hay đăng nhập
app bằng mã QR không tính là đăng nhập mới). Trong 30 ngày đó phiên được làm mới bình thường, nhưng
date_expiredkhông bao giờ vượt mốc 30 ngày. Quá mốc thì làm mới trảerror_session_max_agedù phiên vẫn đang được dùng: đăng nhập lại để có phiên mới. - Đổi mật khẩu thu hồi mọi phiên khác của tài khoản (
error_session_revoked_password_changed). - Giới hạn 30 request / 60 giây cho mỗi IP.
- Không đặt JWT hay refresh token trên URL.
Lỗi error_session_max_age
{
"error": ["error_session_max_age"],
"detail": { "max_age_days": 30 }
}detail.max_age_days là thời hạn tối đa của phiên (số ngày) đang áp dụng trên hệ thống; dùng số này khi hiển thị thông báo
cho người dùng (ví dụ "Phiên đã quá 30 ngày, vui lòng đăng nhập lại"), không ghi cứng.
Error Codes
| HTTP | Code | Mô tả |
|---|---|---|
| 401 | error_refresh_token_invalid | Refresh token / JWT không khớp phiên nào (hoặc vừa được làm mới bởi request khác) |
| 401 | error_refresh_token_reused | Refresh token cũ bị dùng lại: phiên đã bị thu hồi |
| 401 | error_session_expired | Phiên đã hết hạn |
| 401 | error_session_max_age | Phiên đã quá thời hạn tối đa (mặc định 30 ngày kể từ lần đăng nhập), phải đăng nhập lại. Kèm detail.max_age_days |
| 401 | error_session_logged_out | Phiên đã đăng xuất |
| 401 | error_session_revoked | Phiên đã bị thu hồi |
| 401 | error_session_revoked_password_changed | Phiên bị thu hồi do đổi mật khẩu |
| 401 | error_session_revoked_two_factor_enabled | Phiên bị thu hồi do tài khoản bật xác thực 2 lớp |
| 401 | error_session_revoked_two_factor_required | Phiên bị thu hồi do công ty bắt buộc xác thực 2 lớp |
| 403 | error_impersonation_refresh_denied | Phiên hỗ trợ không được làm mới |
| 422 | error_params_required | Thiếu refresh_token hoặc jwt |
| 429 | error_refresh_rate_limited | Quá số lần làm mới cho phép |