Skip to Content
Bảo mậtAPI keys
View as Markdown

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.
  • 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ý.
  • 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:

ScopeCó thể làmDùng cho
readList/đọc orders, sessions, refunds, balancesTích hợp chỉ đọc (analytics, BI)
write_orderMọi read + tạo sessions, tạo orders, cancel ordersBackend storefront
write_refundMọi read + tạo refunds, đánh dấu refund đã executedTool customer support
webhook_manageMọi read + quản lý webhook endpointTool 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.

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.

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ệ [email protected] để:

  • 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 chữ kýNhật ký thay đổi