API 金鑰

API 金鑰可讓你以程式方式存取 badges.ninja REST API。透過 API 金鑰,你可以在自己的應用程式中自動化建立、頒發與管理徽章。

建立 API 金鑰

1. 從側邊欄開啟 API 金鑰 頁面。
2. 點按 建立 API 金鑰,會展開內嵌表單:

3. 為金鑰命名並點按 建立。完整金鑰會在綠色橫幅上顯示一次:

4. 立刻複製金鑰 — 完整金鑰只會顯示一次。若遺失,你必須重新建立一把新的。關閉橫幅後,儀表板僅會顯示金鑰的前綴(例如 bws_a1b2c3d4...);完整金鑰會保存於伺服器端,用於驗證你的請求:

每一列還會顯示金鑰的建立時間,以及一旦金鑰被使用過後的 上次使用 時間戳,讓你能辨識閒置未用的金鑰。

存取範圍

建立金鑰時,你可以將其設為 唯讀,或保留為完全存取:

範圍	允許
完全存取(預設)	讀取 和 寫入 — 列出資料並建立、頒發、更新或刪除。
唯讀	僅允許安全的 GET 請求。任何寫入請求(POST、PUT、PATCH、DELETE)都會被拒絕並回傳 403 Forbidden。

對於只需要 讀取 你資料的整合(報表、儀表板、備份),請使用唯讀金鑰,這樣即使金鑰外洩也無法變更任何內容。在建立表單中勾選 唯讀金鑰;唯讀金鑰會在清單中顯示 唯讀 標記。在存取範圍功能出現之前建立的金鑰保留完全存取。

金鑰格式

API 金鑰以 bws_ 前綴開頭,後接 32 個字元的十六進位字串:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

在請求中使用 API 金鑰

在每個 API 請求的 X-Api-Key 標頭中帶入 API 金鑰:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

API 驗證的完整細節請參閱 驗證 頁面。

各方案的金鑰限制

你可建立的 API 金鑰數量取決於方案:

方案	API 金鑰上限
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

金鑰到期

每把 API 金鑰都會 在建立一年後到期。金鑰一旦到期便會停止驗證請求,如同被刪除一般。請在舊金鑰失效前建立新的金鑰,以避免服務中斷。

刪除金鑰

1. 開啟 API 金鑰 頁面。
2. 找到要刪除的金鑰。
3. 點按 刪除。
4. 確認刪除。

金鑰一經刪除立即失效。任何使用該金鑰的應用程式都會收到驗證錯誤。