Skip to Content
Bảo mậtAPI keys

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à vệ sinh tốt — nó tài liệu hóa intent và giúp bạn sẵn sàng cho việc enforce khi nó được ship — nhưng đọc caveat dưới đây trước khi bạn coi scope là ranh giới bảo mật.

Scope hôm nay là advisory — chúng không được enforce tại gateway. Gateway xác thực chữ ký HMAC của key và inject merchant identity của bạn (X-Merchant-ID / X-Merchant-Domain) đến downstream service, nhưng nó không propagate hay kiểm tra scope của key. Thực tế nghĩa là một sk_ 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 thực ra không bị ngăn tạo refund. Vậy nên scope hẹp không giới hạn blast radius chưa: cho việc lên kế hoạch breach hãy coi mọi secret key là full-access, và dựa vào rotate + revoke nhanh (dưới) làm containment thực sự của bạn. Enforce theo từng scope nằm trong roadmap.

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. Nằm trong roadmap.
  • ❌ 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). Thủ công hôm nay.

Tiếp theo

Xác thực chữ kýNhật ký thay đổi