鑑權與 API Key
/cash/v1/merchant/* 下的商戶介面用 API Key 鑑權。公開內容介面（/cash/v1/content/*）無需憑證；帳戶類介面（聯絡人、API Key 管理）需登入態瀏覽器工作階段。
建立 Key
- 登入後打開主控台的 開發者 → API 金鑰 頁（
/home/developer/keys）。建立 Key 需先通過你本人的個人身份認證（KYC），個人帳戶和企業身份下都一樣；在企業身份下，開發者、管理員、所有者角色可以建立（其他成員看到的是說明而不是列表）。 - 點 建立 API 金鑰，命名、選環境、勾權限範圍，複製 Key——只顯示一次。
| 環境 | 前綴 | 行為 |
|---|---|---|
| 沙箱 | ck_test_… | 合成報價、模擬訂單、不觸達真實供應商、不動資金——見「沙箱與模擬器」 |
| 正式 | ck_live_… | 真實報價與真實訂單 |
| Scope | 授權 |
|---|---|
exchange:read | 幣種、幣對、訂單狀態 |
exchange:write | 報價、建單、沙箱模擬器 |
checkout:write / invoices:write | 收款（收單）介面——你的帳戶開通「收款」產品後才可勾選 |
Key 歸屬你當時所用的主體（個人或企業）；用 Key 建的訂單出現在該帳號的訂單列表。撤銷即刻生效，且不受身份認證要求限制（用登入態呼叫 DELETE /cash/v1/api-keys/{keyId}）。
發送 Key
http
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx失敗碼
| HTTP | code | 含義 |
|---|---|---|
| 401 | CASH_API_KEY_INVALID | Key 缺失、已撤銷或格式錯誤 |
| 403 | CASH_API_KEY_SCOPE_MISSING | Key 缺少本介面所需 scope |
| 403 | CASH_API_KEY_OWNER_INACTIVE | Key 建立者已不是所屬企業的現役成員 |
| 409 | CASH_API_ENVIRONMENT_MISMATCH | live Key 消費了沙箱報價（或反之）——見「沙箱與模擬器」 |
終端使用者國家（合規）
商戶請求來自你的伺服器，平台看不到你的客戶身在何處。請在報價與建單請求帶上 X-End-User-Country: <ISO 3166-1 alpha-2>，平台按該國家套用地區可用性規則，準確性由你負責；不帶該標頭時按你伺服器所在地判定。
最佳實踐
- Key 只放伺服器端，勿寫進瀏覽器或行動端程式碼。
- 輪換：新建 Key → 切流量 → 撤銷舊 Key（也可用登入態呼叫
DELETE /cash/v1/api-keys/{keyId}）。 - 每個串接一把 Key，撤銷時互不影響。