Xác thực

Khóa API (khuyến nghị cho tích hợp)

Khóa API là token truy cập cá nhân gắn với một thành viên trong tài khoản của bạn.

• Tạo khóa trong Cài đặt → Plugin → Khóa API RolChat. Chuỗi bí mật chỉ hiển thị một lần; sau đó chỉ thấy được mười ký tự đầu, và RolChat chỉ lưu hash SHA-256.
• Định dạng: rcp_ theo sau là 32 byte ngẫu nhiên ở dạng base64url, tổng cộng khoảng 45 ký tự. Tiền tố giúp nhận ra khóa trong log và phân biệt với token phiên.
• Scope: được chọn từ danh mục khả năng cố định khi tạo khóa. Khóa không bao giờ làm được nhiều hơn thành viên đã tạo ra nó: ở mỗi lệnh gọi, cả hai điều kiện đều được kiểm tra, khả năng nằm trong scope của khóa và thành viên vẫn còn giữ quyền đó. Thu hẹp vai trò của thành viên thì khóa cũng bị thu hẹp theo.
• Thời hạn: khóa không tự hết hạn. Thu hồi khóa từ trang hồ sơ hoặc bằng DELETE /api/v1/tokens/:id; việc thu hồi có hiệu lực ngay. Không có xoay vòng tại chỗ: hãy thu hồi và tạo khóa mới.
• Việc tạo và thu hồi được ghi vào nhật ký kiểm toán.

Gửi khóa dưới dạng bearer token - không có header riêng cho khóa API:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Yêu cầu dùng khóa API plugin bị giới hạn 300 mỗi phút.

Phiên JWT

Ứng dụng web và SDK di động đăng nhập bằng email và mật khẩu (hoặc Google hay Apple) và nhận một cặp token.

Token	Thời hạn	Ghi chú
Access token	15 phút	RS256, được xác minh với JWKS tại /.well-known/jwks.json
Refresh token	30 ngày	Được xoay vòng ở mỗi lần làm mới; dùng lại token đã xoay vòng sẽ thu hồi toàn bộ chuỗi

Claim: sub (người dùng), acc (tài khoản), rl (vai trò) và, với vai trò theo site, sts (các site được phép).

POST /auth/login, /auth/refresh, /auth/swap-company và /auth/logout là những endpoint duy nhất trong luồng xác thực không được mang header X-Account-Id được mô tả ngay sau đây.

Header X-Account-Id

Mọi yêu cầu đã xác thực, trừ bốn endpoint trên, phải mang tài khoản mà nó đang thao tác:

X-Account-Id: <account uuid>

Máy chủ kiểm tra header có bằng claim acc của token (hoặc tài khoản của khóa API) hay không. Thiếu header trả về 400 missing_required_header; không khớp trả về 403 account_context_mismatch. Header này tồn tại để một lỗi ở client hay một token bị phát lại không bao giờ có thể âm thầm đọc dữ liệu của tenant khác: sự không khớp bị từ chối trước khi bất kỳ truy vấn nào chạy, và mọi dòng log đều quy được về một tài khoản mà không cần giải mã token.

Người dùng nhiều công ty

Một người có thể thuộc nhiều công ty. Mỗi công ty có token riêng (claim acc riêng). Để chuyển đổi:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Đích phải là một trong các available_companies của bên gọi (được trả về khi đăng nhập), nếu không sẽ nhận 403 forbidden. Phản hồi là một cặp access và refresh token mới trong phạm vi công ty đích; refresh token cũ bị thu hồi và sự kiện kiểm toán auth.account.swapped được ghi lại.

Xác thực đa yếu tố

MFA dựa trên TOTP có thể được đăng ký theo từng thành viên và bắt buộc theo tài khoản. Khi bật, POST /auth/login trả về một thử thách và phiên được hoàn tất bằng POST /auth/mfa/verify. Mã dự phòng được cấp khi đăng ký.

Bảo vệ đăng nhập

• Các route đăng nhập bị giới hạn 10 lần thử mỗi IP mỗi phút và 5 lần mỗi email mỗi 15 phút.
• Mười lần đăng nhập thất bại sẽ khóa email trong 30 phút; phản hồi mang code: account_locked.
• Có thể bật reCAPTCHA theo từng hành động (đăng ký, đăng nhập, đặt lại mật khẩu); cấu hình khởi tạo công khai được cung cấp từ GET /api/v1/captcha.