Khoá API

Quản lý → Cài đặt → Khoá API (en: Manage → Settings → API keys).

"Thông tin đăng nhập để một tích hợp truy cập cửa hàng này qua API công khai. Khoá luôn làm được ít hơn người tạo ra nó."

Câu thứ hai là quy tắc quan trọng nhất, và mục cuối trang nói kỹ.

Tạo một khoá

Tạo khoá (en: New key).

Tên — bắt buộc, và biểu mẫu nói rõ vì sao: "Đặt tên cho khoá để sau này bạn nhận ra nó." Sáu tháng nữa, wbk_a1b2c3… không nói cho bạn biết gì cả; "Đồng bộ kho Acme" thì có.

Phạm vi — chia làm Quyền nội dung và Quyền cửa hàng. Phải chọn ít nhất một.

Hãy chọn ít nhất mức đủ dùng. Một tích hợp chỉ đọc đơn hàng thì cho đúng orders.read, không hơn.

Chuỗi bí mật hiện đúng một lần

Sau khi tạo, một hộp thoại hiện ra:

Sao chép khoá ngay bây giờ — "Đây là lần duy nhất khoá được hiển thị. Hãy lưu vào nơi an toàn — nếu mất, hãy thu hồi khoá này và tạo khoá mới."

Điều này đúng theo nghĩa đen. Khoá được lưu ở dạng đã băm (SHA-256), nên không ai — kể cả người vận hành nền tảng — đọc lại được. Không có nút "hiện lại".

Danh sách về sau chỉ hiện tiền tố (wbk_a1b2c3…), đủ để phân biệt các khoá và vô dụng nếu dùng làm thông tin đăng nhập.

Mất khoá thì cách sửa là thu hồi và tạo cái mới. Đó không phải bất tiện — nó là điều duy nhất khiến "chỉ hiện một lần" có ý nghĩa.

Danh sách khoá

Các cột: Tên, Khoá (tiền tố), Quyền, Dùng lần cuối, Trạng thái.

Dùng lần cuối là cột hữu ích nhất trong việc dọn dẹp: một khoá Chưa dùng sau nhiều tháng gần như chắc chắn là khoá bỏ quên, và mọi khoá bỏ quên đều là một cánh cửa mở không ai canh.

Thu hồi

Thu hồi — "Mọi thứ đang dùng “{tên}” sẽ ngừng hoạt động ngay lập tức. Không thể hoàn tác."

Khoá bị thu hồi vẫn nằm trong danh sách với trạng thái Đã thu hồi, nên bạn còn thấy nó từng tồn tại và từng làm gì.

Dùng khoá

Gửi chuỗi bí mật trong header Authorization của mọi yêu cầu. Không session, không cookie, không đăng nhập.

curl https://api.your-host/api/v1/products \
  -H "Authorization: Bearer wbk_your_secret_here"

Một khoá thuộc đúng một cửa hàng, nên không có mã cửa hàng trong đường dẫn — không có {siteId} ở bất cứ đâu trong /api/v1. Một khoá mà chỉ cần sửa URL là trỏ được sang cửa hàng khác thì bán kính thiệt hại của nó phụ thuộc vào sự trung thực của người gọi.

Một agency vận hành năm cửa hàng thì giữ năm khoá.

Thiếu phạm vi thì API trả 403 insufficient_scope — không phải 404, để bạn phân biệt được "bạn không được phép" với "nó không tồn tại".

Toàn bộ chi tiết ở API công khai.

Hai giới hạn, không phải một

Đây là phần mà tài liệu này tồn tại để nói:

Giới hạn 1 — phạm vi của chính khoá. Thứ bạn tích lúc tạo.

Giới hạn 2 — vai trò hiện tại của người đã tạo khoá. Bảng nói: "Khoá còn bị giới hạn bởi vai trò của người tạo — nếu sau này quyền của người đó bị thu hẹp thì khoá cũng vậy."

Quyền được phân giải trực tiếp ở từng yêu cầu, không bao giờ chụp lại lúc tạo khoá. Nên một khoá do quản trị viên tạo, người này về sau bị hạ xuống Người xem, mất quyền ghi ở yêu cầu kế tiếp — không cần một đợt thu hồi nào và bên tích hợp không phải ghi sổ gì.

Hai hệ quả thực tế:

• Khi một người rời công ty, hãy hạ vai trò hoặc gỡ họ khỏi site. Việc đó thu hẹp mọi khoá họ từng tạo, cùng lúc, mà không cần đi tìm từng cái.
• Một khoá có thể ngừng chạy dù bạn không đụng gì tới nó. Nếu một tích hợp đột nhiên nhận 403, hãy kiểm vai trò của người đã tạo khoá trước khi nghi ngờ đoạn code.

Nếu phạm vi đã lưu của một khoá không còn hợp lệ nữa, API trả 403 key_unusable — "Không phải lỗi của người gọi, và câu trả lời nói rõ như vậy." Cách sửa là tạo khoá mới.

Khoá API khác với token của ứng dụng

wbk_ là khoá do chủ cửa hàng tạo cho công cụ của mình.

wba_ là token cấp cho một ứng dụng khi khách cài nó từ chợ ứng dụng.

Cả hai đều dùng được trên /api/v1 và hành xử y hệt nhau khi đã qua cửa. Chúng khác nhau ở chỗ ai giữ và cấp thế nào. Xem Xây một app.