驗證

所有對 badges.ninja 的 API 請求皆需驗證。本頁說明如何驗證你的請求。

基底 URL

https://api.badges.ninja

所有 API 端點皆相對於此基底 URL。

API 金鑰驗證

主要的驗證方式是在 X-Api-Key 標頭中傳入 API 金鑰。

取得 API 金鑰

從儀表板取得:

1. 於 badges.ninja 登入。
2. 前往側邊欄的 API 金鑰。
3. 點按 建立 API 金鑰。
4. 複製金鑰(僅顯示一次)。

透過 API 取得:

API 金鑰也可透過 API 搭配 Cognito 驗證流程的 JWT 權杖進行管理。最簡單的做法請參閱儀表板。

使用你的 API 金鑰

在每次請求中加入 X-Api-Key 標頭:

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

API 金鑰格式

金鑰以 bws_ 為前綴:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

請求格式

• GET 請求以查詢字串傳入參數
• POST 與 PUT 請求以 JSON 主體傳送一個 parameters 物件
• 所有回應皆以 JSON 傳回,並具備 Content-Type: application/json

POST/PUT 請求結構

{
  "parameters": {
    "name": "My Badge",
    "description": "A sample badge"
  }
}

範例請求

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "My Organization",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

範例回應

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

速率限制

API 請求受速率限制保護。若超過上限,你會收到 429 Too Many Requests 回應。請稍候數秒後重試。

公開端點

部分端點無需驗證。它們是位於 /certify-badge/ 之下的 公開驗證端點,允許任何人驗證徽章憑證。