颁发者 API

管理徽章颁发者 — 颁发徽章的组织或个人。

所有端点都需要通过 X-Api-Key 头进行认证。参阅 认证。

创建颁发者

创建一个新的徽章颁发者。

POST /issuers

参数

参数	类型	必填	描述
name	string	是	组织名称（至少 3 个字符）
url	string	是	组织网站（必须是有效的 HTTP/HTTPS URL）
email	string	是	颁发者的联系邮箱
logo	string	否	Base64 编码的图片（PNG 或 JPG）
linkedinOrganizationId	string	否	LinkedIn 公司页面的数字 ID。设置后，该颁发者的每个公开凭证页面都会显示 Add to LinkedIn Profile 按钮。

示例

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": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

响应

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

说明

• 计入套餐的颁发者数量上限（Free：2，Starter：5，Pro：10）。不扣除配额。
• 如果颁发者邮箱与你的账户邮箱一致，颁发者会被自动验证。
• 如果邮箱不同，会向该颁发者邮箱发送一封验证邮件。
• 配置好颁发者后，请使用 凭证 API 开始在该颁发者名下颁发凭证。

---

列出颁发者

获取你创建的所有颁发者。

GET /issuers

示例

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

响应

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp 是以毫秒为单位的 Unix 时间戳。当颁发者数量超过一页所能容纳时，还会返回 lastEvaluatedKey 用于分页。

---

验证颁发者

使用发送到颁发者邮箱的验证码来验证颁发者。

POST /issuers/{issuerId}/verify

参数

参数	类型	必填	描述
issuerId	string	是	颁发者 ID（路径参数）
code	string	是	邮件中的验证码

示例

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

响应

一个纯字符串：

"issuer has been verified"

---

删除颁发者

删除颁发者。该颁发者不得有任何关联的徽章。

DELETE /issuers/{issuerId}

示例

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

响应

一个纯字符串：

"issuer has been deleted"

错误

• 400 — 该颁发者仍有关联的徽章：issuer has {n} badge(s) linked — delete the badges first。删除操作仅受关联徽章限制 — 凭证不会阻止删除。
• 404 — 未找到颁发者

---

更新颁发者

更新颁发者的字段。只有未验证的颁发者可以编辑 — 颁发者一旦通过验证，此端点会返回 400 verified issuers cannot be edited，以保证凭证的稳定性。编辑颁发者会重新生成其验证码：如果 email 与你的账户邮箱一致，颁发者会被自动重新验证，否则会向该地址发送一封新的验证邮件。

PUT /issuers/{issuerId}

参数

参数	类型	必填	描述
issuerId	string	是	颁发者 ID（路径参数）
name	string	否	新名称
url	string	否	新 URL
email	string	否	新邮箱（除非与你的账户邮箱一致，否则会发送新的验证邮件）
logo	string	否	新的 Base64 编码徽标
linkedinOrganizationId	string	否	新的 LinkedIn 组织 ID（或使用空字符串清除）

响应

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

错误

• 400 — verified issuers cannot be edited（该颁发者已通过验证）
• 400 — not authorized（该颁发者属于其他账户）
• 404 — 未找到颁发者