Session token một lần

Session token là JWT ES256 TTL 10 phút do Core API cấp cho backend của bạn, dùng để đổi lấy một phiên hội thoại. Biến ngữ cảnh không nằm trong JWT — lưu ở server và validate lúc đổi token.

Luồng hoàn chỉnh

Backend của bạn                    Core API                       Client
─────────────────────────────────────────────────────────────────────────
POST /v1/sessions/token  ───────►  cấp token (ES256, 1 lần)
  (Authorization: Bearer avk_…)      biến lưu ở server
        ◄────── { token }
        ──── trả token cho client ─────────────────────►  POST /v1/public/sessions/exchange
                                                          (Core API kiểm ORIGIN
                                                           rồi mới tiêu token)
                                                          ◄── { livekitUrl, accessToken,
                                                                endToken, sessionId }
POST /v1/public/sessions/{id}/end ◄───────────────────────  khi người dùng kết thúc
  (kèm endToken)

Bảo đảm bảo mật

1. Một lần: tiêu token bằng UPDATE nguyên tử consumed_at IS NULL — dùng lại chỉ nhận 401, không phân biệt nguyên nhân (không dò thông tin).
2. Kiểm tra origin trước khi tiêu: trang lạ thử đổi token không làm hỏng token của trang thật.
3. Thu hồi API key vô hiệu token: thu hồi API key cũng đánh dấu các token chưa tiêu của key đó — hiệu lực ngay lập tức.
4. Hết hạn 10 phút: token không tiêu trong 10 phút tự vô hiệu.

Lỗi khi đổi token

Mã	HTTP	Khi nào
INVALID_SESSION_TOKEN	401	Sai, hết hạn hoặc đã dùng
ORIGIN_NOT_ALLOWED	403	Origin không nằm trong allowlist agent
ENTITLEMENT_REQUIRED	402	Vượt hạn mức tổ chức (token còn nguyên, thử lại được sau khi nâng hạn mức)
RATE_LIMITED	429	Thách thức quá nhiều yêu cầu

SDK Web (createTokenSessionProvider) và widget triển khai đúng luồng này sẵn — bạn chỉ cần route cấp token phía backend (xem Quickstart widget).