認證與 API key

說明 API key 的使用方式、認證結果、保存規則、撤銷與輪替流程。

資料平面的所有請求都以 API key 認證。把 key 放進每個請求的 X-API-Key header 即可。

curl https://api.blockchainsecurity.asia/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"

未取得 API key？歡迎先免費試用。部分端點支援免 API key 測試（同 IP 每日 10 次），方便評估回傳格式與串接流程。

若需完整 API 模組、高頻率查詢或商用正式接入，請聯絡 [e-mail] 申請專屬 API key，以享有完整額度與用量計費。

API key 長什麼樣子

• API key 長什麼樣子

  • API key 以 ak_live_ 開頭，後接一段隨機字串，例如 ak_live_3f9a2c7b8e1d4a60...。

  • 管理後台與操作紀錄只會顯示 key 的前綴或部分遮蔽字元，用於辨識，不會顯示完整明碼。

  • 系統只保存 key 的雜湊值，不保存完整明碼。若遺失明碼，無法取回，只能撤銷後重新建立。

請將 API key 視同密碼保存。建議放在伺服器端環境變數或密鑰管理服務中，切勿寫入前端程式碼、公開 repository、版本控制或公開頁面。

認證結果

情況	HTTP	code	說明
未帶 key，但端點允許免費試用	200	—	依免費試用額度處理請求
未帶 key，且端點需認證	401	unauthorized	請求未提供有效 API key
API key 無效或已撤銷	401	unauthorized	key 不存在、格式錯誤或已被撤銷
API key 有效但權限不足	403	forbidden	key 無權呼叫該 endpoint 或 API 模組
Credit 不足	402	insufficient_credit	剩餘額度不足，無法處理需計費請求
超過限流	429	rate_limited	請求頻率超過目前方案或 endpoint 限制
認證通過	200	—	繼續處理請求

為避免洩漏「某把 key 是否存在」，key 無效、已撤銷或不存在時，系統皆回傳 401 unauthorized。

取得與管理金鑰

API key 由客戶方管理員在管理後台建立與管理，可執行以下操作：

• 建立 — 指定 key 名稱、方案、權限範圍與初始 Credit，建立後取得一次性明碼。

• 撤銷 — 立即停用該 key；撤銷後，使用該 key 的請求一律回傳 401 unauthorized。

• 調整 Credit — 依方案或授權額度，為指定 key 增加或減少可用 Credit。

輪替金鑰

系統不會自動輪替，建議流程如下：

1

建立新 key

請管理員建立一把新 key，並妥善保存明碼。

2

切換整合

將應用程式、後端服務或排程任務改用新 key，並重新部署。

3

觀察請求

確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。

4

撤銷舊 key

確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。

追蹤每個請求

每次回應都會包含 request_id，並可能同步出現在 X-Request-Id header。當你回報問題、查詢扣點、追蹤延遲或進行稽核時，請提供該 request_id 以加速定位。

下一步

錯誤處理限流