Bảo mật khi tích hợp NextX

Những gì NextX bảo đảm, và những gì hệ thống của bạn phải làm để dữ liệu workspace an toàn.

1. Chứng từ

client_secret của app (nxs_…) và API key (nxk_…) chỉ hiện một lần — mất là tạo lại, không ai xem lại được.
Token OAuth2 sống 3600 giây; trường refresh_token trả về luôn rỗng — hết hạn thì gọi lại endpoint lấy token.
Mỗi workspace một token riêng (workspace_id của workspace đã cài app).
Giữ secret/khóa trên máy chủ của bạn — không nhúng vào app di động, trang web chạy ở trình duyệt, kho mã hay log.

2. Scope tối thiểu

Scope thực cấp = requested ∩ allowed (của app) ∩ granted (workspace consent) ∩ phân hệ workspace đang mua — gọi ngoài scope là 403 (insufficient_scope ở route gateway chặn, Permission required: … ở route còn lại).
Gateway kiểm quyền theo từng endpoint; workspace tự chọn cấp scope nào khi cài app.
Chỉ xin đúng scope cần — workspace dễ đồng ý hơn, lộ token thì thiệt hại nhỏ hơn.

3. Webhook có signature

X-NextX-Signature-256: sha256=<hex> = HMAC-SHA256(secret, {ts}.{raw_body}) — tính trên raw body chưa parse JSON.
Từ chối nếu X-NextX-Timestamp lệch quá ~5 phút (chống replay).
Khử trùng theo id (evt_…) — cùng một sự kiện có thể đến nhiều lần khi retry.
Secret webhook (whsec_…, chuẩn Standard Webhooks; webhook cũ có thể còn whk_sec_…) chỉ trả về một lần — lúc webhook của dịch vụ được tạo lần đầu (created: true) hoặc khi xoay secret — lưu kỹ.
Secret whsec_… còn kèm header chuẩn webhook-id · webhook-timestamp · webhook-signature — kiểm bằng thư viện standardwebhooks có sẵn thay vì tự viết.

4. Đường truyền

Chỉ HTTPS. URL webhook trỏ IP nội bộ/private bị chặn (SSRF guard) — chỉ nhận HTTPS công khai.
Endpoint phải trả 2xx trong 15 giây; lỗi/timeout thì giao tối đa 8 lần (7 lần retry trong ~24 giờ), lỗi liên tục thì tạm ngắt (circuit breaker).
Giới hạn mặc định 600 request/phút mỗi app — gặp 429 thì đọc Retry-After rồi giãn nhịp.

5. Gửi lại an toàn (Idempotency-Key)

Mọi thao tác ghi (POST/PUT/PATCH) gọi bằng API key hoặc token ứng dụng nhận header Idempotency-Key — tự sinh một mã (vd UUID) cho mỗi thao tác.
Mạng chập, gửi lại cùng mã trong 24 giờ ⇒ nhận lại đúng kết quả lần đầu (header Idempotency-Replayed: true), không tạo bản ghi thứ hai. Lần đầu còn đang chạy ⇒ 409, đợi giây lát rồi gửi lại.
Cùng mã mà khác đường dẫn hoặc nội dung ⇒ 422 — đừng dùng lại mã cho thao tác khác. Lần đầu lỗi (không phải 2xx) thì mã được nhả, gửi lại sẽ chạy lại.

6. Xoay và thu hồi

API key: thu hồi ở Cài đặt → API Keys & Webhooks — mất hiệu lực gần như ngay lập tức.
Đổi khóa không gián đoạn: tạo khóa mới, đối tác chuyển xong rồi mới thu hồi khóa cũ.
Xoay secret webhook giữ secret cũ còn hiệu lực 7 ngày: trong thời gian đó NextX gửi X-NextX-Signature-256 (secret mới) kèm X-NextX-Signature-256-Previous (secret cũ) — chấp nhận một trong hai, rồi bỏ secret cũ.

7. Báo lỗ hổng

Gửi mô tả + cách tái hiện tới support@nextx.vn, tiêu đề bắt đầu bằng [Bảo mật]. Vui lòng không công bố trước khi NextX xác nhận đã vá.
Chỉ thử trên sandbox https://api-dev.nextx.vn — không thử trên dữ liệu khách thật.

Danh sách kiểm trước khi lên thật

☐ Secret/khóa nằm trong kho secret — không trong mã nguồn, không in ra log
☐ Chỉ xin đúng scope cần
☐ Verify signature + timestamp mọi webhook, khử trùng theo id, trả 2xx trong 15 giây
☐ Trong lúc xoay secret: chấp nhận signature mới HOẶC Previous
☐ Mọi thao tác ghi gửi Idempotency-Key riêng; gửi lại khi mạng chập thì dùng lại đúng mã đó
☐ Xử lý 401 (token/khóa hết hạn, thu hồi) · 403 (thiếu scope) · 429 (đợi Retry-After)
☐ Đã chạy thử trọn luồng trên sandbox https://api-dev.nextx.vn

Câu hỏi tích hợp thông thường cũng gửi support@nextx.vn.