Đổi lấy token
Đổi publishable key và danh tính end-user lấy token phiên chat.
POST /v2/token là endpoint duy nhất mà một trình duyệt được phép gọi bằng
pk. Widget gọi nó tự động; bạn chỉ cần đọc trang này nếu bạn tự triển khai
lại phần token (ví dụ token-url của riêng bạn), hoặc muốn hiểu cơ chế
user-hash.
Request
POST https://api.harnix.vn/v2/token
Content-Type: application/json
X-Publishable-Key: pk_xxxxxxxxxxxxxxxx{
"end_user_id": "user_42",
"user_hash": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3...",
"expires_at": 1735689600
}Header quyết định hình thức, không phải body:
| Header | Body | Hình thức |
|---|---|---|
X-API-Key | end_user_id | Server-to-server: tự khẳng định danh tính, tin ngay. |
X-Publishable-Key | end_user_id + user_hash + expires_at | Ký bởi bạn (mức 2). |
X-Publishable-Key | anonymous_id (UUID) | Ẩn danh (mức 1). |
Có cả X-API-Key lẫn X-Publishable-Key trong cùng request: API key
thắng, pk/Origin bị bỏ qua hoàn toàn.
Response
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"expires_at": 1735693200,
"end_user": { "id": "3fae...", "kind": "identified" }
}token là một JWT (HS256), sống trong khoảng thời gian ngắn (mặc định 1
giờ). kind là một trong anonymous, identified, service. Dùng
token này làm Authorization: Bearer <token> cho mọi request tiếp theo.
Ký user_hash
Công thức: HMAC-SHA256(identity_secret, "{end_user_id}:{expires_at}"), kết
quả ở dạng hex. identity_secret lấy một lần từ Console → Tích hợp →
Tạo lại khoá bí mật (hiện ra đúng một lần lúc tạo, lưu nó an
toàn ở backend của bạn).
import { createHmac } from "node:crypto";
function signUserHash(identitySecret, endUserId, expiresAt) {
return createHmac("sha256", identitySecret)
.update(`${endUserId}:${expiresAt}`)
.digest("hex");
}
const expiresAt = Math.floor(Date.now() / 1000) + 3600; // tối đa 24h
const userHash = signUserHash(process.env.HARNIX_IDENTITY_SECRET, "user_42", expiresAt);Cửa sổ tối đa 24 giờ
expires_at không được xa hơn 24 giờ kể từ lúc ký — một chữ ký rò ra
ngoài không thể trở thành vé vĩnh viễn. Vượt quá, hoặc đã qua hạn, trả về
user_hash_expired. display_name/metadata (nếu bạn gửi kèm) không
nằm trong chữ ký — chúng vẫn là lời khẳng định của bạn, không phải thứ
end-user tự chứng minh.
end_user.metadata (tuỳ chọn)
Bạn có thể gửi kèm display_name và metadata (một object JSON phẳng, tối
đa 4 KB, không lồng object/array) trong body — chúng được lưu lại trên hàng
end-user, hữu ích để hiển thị trong console. Không lồng — một giá trị là
object hay array bị từ chối với validation_error.
Giới hạn tần suất
Đổi token qua pk (ẩn danh hoặc có ký) bị giới hạn theo (pk, IP), mặc
định 60 lần/phút — vượt quá trả rate_limited với retry_after. Đổi bằng
X-API-Key (server-to-server) không bị giới hạn ở endpoint này.
Token không revoke được trước khi hết hạn
Một token đã phát ra không thể thu hồi giữa chừng — nhưng mọi request vẫn tra lại trạng thái end-user và tổ chức ở mỗi lần gọi, nên chặn một end-user hay tạm ngưng một tổ chức có hiệu lực ngay từ request kế tiếp, dù token còn hạn.
Bước tiếp theo
- Server-to-server — gọi
/v2/chatthẳng bằng API key, không cần đổi token. - Lỗi —
invalid_publishable_key,invalid_user_hash,user_hash_expired,origin_not_allowed,rate_limited.