# API keys Ba loại credential, ba mô hình threat. ## `pk_` — Publishable - Được thiết kế để ship đến trình duyệt. Gửi dưới dạng header `X-Client-ID` trên mọi request B2B đã ký, cũng được nhúng trong bundle SDK cho việc mở checkout phía client. - Có thể nhận diện tài khoản của bạn; không thể tạo session, đọc data của merchant khác, hoặc kích hoạt bất kỳ thứ gì destructive. - Một publishable key bị lộ là sự cố **mức thấp**. ## `sk_` — Secret (khóa ký HMAC) - Khóa ký HMAC-SHA256 cho mọi lệnh gọi B2B API — xem [Xác thực](https://docs.infraio.xyz/vi/api-reference/authentication). - Không bao giờ di chuyển qua dây. Chỉ chữ ký dẫn xuất theo từng request. Nên bạn chỉ phải lo lắng về lộ lọt ở lớp *lưu trữ* (env vars, git, log), không phải ở lớp transport. - Chỉ phía server. Không bao giờ nên xuất hiện trong bundle trình duyệt, repo public, screenshot, hay tin nhắn chat. - Một secret bị lộ là sự cố **mức cao**. ## `whsec_` — Secret ký webhook - Dùng để xác thực chữ ký trên các delivery webhook **inbound** từ chúng tôi đến server của bạn. Xem [Xác thực chữ ký](https://docs.infraio.xyz/vi/webhooks/signature-verification). - Riêng cho mỗi webhook endpoint — nếu bạn có 3 endpoint đã đăng ký, bạn có 3 secret `whsec_` khác nhau. Môi trường được mã hóa trong prefix: `whsec_live_…` / `whsec_test_…`. - Chỉ phía server. Giống như `sk_`, không bao giờ di chuyển qua dây — chỉ dùng để xác thực HMAC local. - **Rotate có cửa sổ grace 24 giờ.** Bấm Rotate và secret trước đó vẫn được chấp nhận trong 24h song song với secret mới (delivery mang cả `X-Signature` và `X-Signature-Prev`), để bạn có thể redeploy verifier mà không cần giữ traffic. - **Reveal-existing-secret** có sẵn, gate bởi 2FA mới và ghi vào audit log — cho trường hợp secret bị mất và rotate không chấp nhận được. Lập trường mặc định của dashboard là "rotate, đừng reveal". - Một webhook secret bị lộ cho phép attacker fake event đến URL của bạn. **Mức trung bình đến cao** tùy thuộc bạn tin payload event đến mức nào. ## Scope Secret key được scope. Dashboard cho phép bạn phát hành key với một trong các bundle scope sau: | Scope | Có thể làm | Dùng cho | | --- | --- | --- | | `read` | List/đọc orders, sessions, refunds, balances | Tích hợp chỉ đọc (analytics, BI) | | `write_order` | Mọi `read` + tạo sessions, tạo orders, cancel orders | Backend storefront | | `write_refund` | Mọi `read` + tạo refunds, đánh dấu refund đã executed | Tool customer support | | `webhook_manage` | Mọi `read` + quản lý webhook endpoint | Tool DevOps | Một key "full access" mặc định nhận được cả bốn. Phát hành key theo mục đích vẫn là thực hành tốt vì nó tài liệu hóa intent, nhưng đọc caveat dưới đây trước khi bạn coi scope là ranh giới bảo mật. > **Warning:** > > **Scope chưa được enforce.** Một `sk_` key bị lộ với *bất kỳ* scope > nào đều có thể gọi *bất kỳ* endpoint `/b2b/v1/*` nào cho merchant của > bạn. Một key `read` không bị ngăn tạo refund. Scope hẹp **không** > giới hạn thiệt hại của một vụ lộ key: khi lên kế hoạch bảo mật, hãy > coi mọi secret key là full access và dựa vào rotate và revoke nhanh > (dưới) để khống chế vụ lộ. ## Rotate 1. **Tạo key mới.** Dashboard → **Developers → API keys** → **+ Add key**. Chọn scope. Dashboard hiển thị secret **một lần** — lưu nó ngay lập tức. 2. **Roll env var** sang giá trị mới trên mọi môi trường. Deploy. 3. **Xác minh traffic.** Dashboard hiển thị count request theo từng key theo thời gian thực. Chờ count của key cũ giảm về 0. 4. **Revoke key cũ.** Cùng màn hình → menu kebab → **Revoke**. > **Warning:** > > **Không có cửa sổ overlap tự động hôm nay** — khi bạn revoke một > key, bất kỳ request đang chạy nào ký bằng nó đều nhận `401`. Lên kế > hoạch rotate phù hợp: deploy key mới trước, drain traffic từ key cũ, > rồi revoke. ## Revoke khẩn cấp Nếu một key đã lộ (trong lịch sử git, trong bundle public, trong stack trace bị log, trong báo cáo pen-test của partner) — revoke ngay lập tức, kể cả với cái giá là một số request fail. Tốt hơn fail ồn ào hơn là để attacker giữ một credential hợp lệ. Các bước: 1. **Dashboard → Developers → API keys → [key] → Revoke now.** Hiệu lực tức thời; không có grace period. 2. Phát hành replacement và deploy. 3. Audit hoạt động gần đây — dashboard hiển thị 30 ngày gần nhất của request theo từng key với IP và endpoint bị chạm. Nếu bạn nghi ngờ breach rộng hơn một key, liên hệ contact@lartech.xyz để: - Lấy export audit log đầy đủ cho tài khoản merchant của bạn - Rotate webhook secret hàng loạt - Tùy chọn freeze tài khoản trong khi bạn điều tra ## Best practice lưu trữ - **Chỉ env var.** Không bao giờ commit secret vào git, kể cả trong một `.env.example` ghi "REPLACE ME". - **Key theo từng môi trường.** `sk_test_…` và `sk_live_…` khác nhau cho dev/staging/prod, lấy từ secrets manager của bạn (AWS Secrets Manager, Vault, Doppler, …). - **Hạn chế truy cập env var.** Trong Kubernetes, mount như là `Secret`, không phải `ConfigMap`. Trong Vercel/Netlify, dùng scope environment-variable không phải global cấp project. - **Đừng log request với body.** Kể cả khi debug — chữ ký HMAC của bạn trong `X-Signature` là single-use nhưng business payload có thể include PII. ## Những thứ HIỆN CHƯA hỗ trợ - ❌ **IP allowlist** cho secret key. - ❌ **Token theo từng user scope kiểu OAuth.** Mô hình key hiện tại là theo từng merchant, không theo từng user. - ❌ **Rotate key tự động** (ví dụ rotate hàng tuần được enforce bởi platform). Việc rotate là thủ công. ## Tiếp theo - [Xác thực](https://docs.infraio.xyz/vi/api-reference/authentication) — thuật toán ký chính xác cho lệnh gọi B2B. - [Webhooks → Xác thực chữ ký](https://docs.infraio.xyz/vi/webhooks/signature-verification) — cách `whsec_` được dùng trên event đến.