Harnix

Xác thực

Ba mức danh tính: publishable key, publishable key có ký, token của riêng bạn.

Mọi request tới các endpoint public (/v2/token, /v2/agents, /v2/conversations, /v2/chat, /v2/runs) đều xác thực bằng đúng một trong hai cách:

  • một token phiên chat (Authorization: Bearer <token>) — cấp cho một end-user cụ thể, hết hạn sau một khoảng thời gian ngắn;
  • một API key (X-API-Key: <key>) — dùng khi backend của bạn gọi thẳng thay mặt end-user, xem Server-to-server.

Trang này nói về cách lấy token. Có ba mức danh tính khác nhau, tương ứng ba cách khác nhau để có một token — chọn theo việc bạn có muốn end-user có danh tính hay không, và nếu có, ai là người xác nhận danh tính đó.

Ba mức danh tính

1. Ẩn danh (pk không ký)

Đơn giản nhất. Widget tự sinh một anonymous_id (UUID) ngẫu nhiên, lưu nó trong localStorage, và gửi kèm pk để đổi token. Bạn không cần biết end-user này là ai. Phù hợp cho một trợ lý FAQ công khai không cần gắn với tài khoản người dùng thật.

<harnix-chat pk="pk_xxxxxxxxxxxxxxxx"></harnix-chat>

Không có tham số nào khác — widget tự lo phần còn lại.

2. Có danh tính, ký bởi bạn (pk + user-hash)

Bạn biết end-user này là ai (ví dụ họ đã đăng nhập vào sản phẩm của bạn), nhưng bạn không muốn để lộ API key ra trình duyệt. Backend của bạn ký một chữ ký HMAC ngắn hạn, truyền nó vào widget qua ba thuộc tính:

<harnix-chat
  pk="pk_xxxxxxxxxxxxxxxx"
  end-user-id="user_42"
  user-hash="a94a8fe5ccb19ba61c4c0873d391e987982fbbd3..."
  expires-at="1735689600"
></harnix-chat>

Widget gửi cả ba trường này cho POST /v2/token; Harnix xác minh chữ ký bằng identity secret của tổ chức bạn (không bao giờ rời khỏi backend của bạn). Xem công thức chữ ký và ví dụ code ở Đổi lấy token.

Không có nhánh im lặng thành ẩn danh

Nếu bạn gửi end-user-id mà thiếu user-hash hoặc expires-at, request bị từ chối (invalid_user_hash) — nó không âm thầm rơi về mức ẩn danh. Việc mint một token có danh tính mà không có chữ ký hợp lệ là điều Harnix cố tình chặn.

3. Token của riêng bạn (token-url hoặc token)

Bạn muốn tự kiểm soát hoàn toàn việc phát hành token — ví dụ áp thêm logic riêng trước khi cho phép chat, hoặc bạn đã có một endpoint phát hành token nội bộ. Hai lựa chọn:

Widget tự POST tới endpoint của bạn (same-origin, kèm cookie phiên hiện tại) mỗi khi cần một token mới:

<harnix-chat token-url="/api/harnix-token"></harnix-chat>

Endpoint đó là của bạn, không phải của Harnix — nó tự xác thực người dùng theo cách của sản phẩm bạn (session cookie chẳng hạn), rồi gọi POST /v2/token bằng API key ở phía server, và trả về { "token": "..." }.

Endpoint phát token bắt buộc phải xác thực trước

Chỉ phát token cho người dùng mà phiên đăng nhập của chính bạn xác nhận đang đăng nhập, và chỉ với id của đúng người đó. Một endpoint phát token mà không kiểm tra phiên sẽ cho bất kỳ ai chat dưới danh nghĩa — và đọc hội thoại của — bất kỳ người dùng nào của bạn.

Đúng một trong ba

pk, token-url, token — widget yêu cầu đúng một trong ba thuộc tính này có mặt. Có hai (hoặc không có cái nào) là lỗi cấu hình, widget từ chối render thay vì đoán.

Origin

Cả pk (đổi token trực tiếp) lẫn token đã cấp (mọi request tiếp theo) đều bị kiểm tra Origin so với Origin được phép đã cấu hình cho tổ chức bạn (Console → Tích hợp). So khớp chính xác scheme + host + port, không có wildcard subdomain. Sai origin → origin_not_allowed (403).

Bước tiếp theo

  • Đổi lấy token — công thức POST /v2/token đầy đủ, kể cả cách ký user-hash.
  • Server-to-server — gọi bằng API key, không qua widget.
  • Lỗi — ý nghĩa từng mã lỗi liên quan tới xác thực.

Trên trang này

Ba mức danh tính1. Ẩn danh (pk không ký)2. Có danh tính, ký bởi bạn (pk + user-hash)3. Token của riêng bạn (token-url hoặc token)OriginBước tiếp theo