合作夥伴 API（B2B）
身分驗證
使用合作夥伴入口網站核發的 API 金鑰進行身分驗證，以及輪替、限制或撤銷金鑰的方法。
金鑰格式#
text
esk_live_<prefix:10>_<secret:40>金鑰由 10 位前綴（在入口網站中用於識別金鑰的公開識別碼）與 40 位秘密值組成的英數字串。esimoa 僅儲存 SHA-256 雜湊，因此完整金鑰只在核發時顯示一次，之後無法找回。
注意
與開發者中心的公開 API 金鑰（esk_live_<32 位>）格式不同。混用到對方 API 會被 INVALID_API_KEY 拒絕。
傳送金鑰#
每個請求都透過 X-API-Key 標頭傳送金鑰，也支援 Authorization: Bearer。未傳送金鑰回傳 401 API_KEY_REQUIRED，格式錯誤或不存在的金鑰回傳 401 INVALID_API_KEY。
http
# Preferred
X-API-Key: esk_live_AbCdE12345_<40-character secret>
# Also accepted
Authorization: Bearer esk_live_AbCdE12345_<40-character secret>核發金鑰#
- 1合作夥伴入口網站 → API 金鑰 — 建立新金鑰。
- 2填寫名稱，並可選填到期時間（1 分鐘後至 3 年內）與 IP 允許清單。
- 3立即複製僅顯示一次的金鑰，並儲存到密鑰管理工具或伺服器環境變數中。
每個帳號預設最多可同時擁有 5 組有效金鑰（未撤銷且未到期的金鑰）。
輪替金鑰#
輪替會建立名稱、權限、IP 清單與到期時間相同的新金鑰，舊金鑰僅在您設定的寬限期（0–72 小時）內繼續可用，之後到期。請在此期間部署新金鑰。寬限期為 0 時舊金鑰立即失效。
注意
已撤銷或已到期的金鑰無法輪替 — 請核發新金鑰。寬限期結束後舊金鑰會收到 401 KEY_EXPIRED。
IP 允許清單#
每組金鑰最多可指定 20 個允許呼叫的 IPv4/IPv6 位址或 CIDR 網段（如 203.0.113.10、198.51.100.0/24）。留空表示不限制，清單外的請求回傳 403 IP_NOT_ALLOWED。請填寫伺服器的對外（egress）IP。
撤銷金鑰#
金鑰外洩或不再使用時，請立即在入口網站中撤銷。金鑰不做快取，下一個請求起即回傳 401 KEY_REVOKED。緊急情況下 esimoa 可撤銷金鑰或停用帳號，被停用帳號的所有金鑰都會收到 403 PARTNER_SUSPENDED。
成員權限#
| 角色 | 可執行操作 |
|---|---|
| OWNER | 全部功能 |
| ADMIN | 管理金鑰與成員 |
| DEVELOPER | 管理金鑰、瀏覽商品 |
| VIEWER | 唯讀 |
僅 OWNER、ADMIN、DEVELOPER 可以核發、輪替或撤銷金鑰，所有成員皆可查看金鑰列表。