认证

所有对 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 token。关于最简方式,请参阅控制台。

使用 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 请求通过 query string 传递参数
• POST 与 PUT 请求发送带 parameters 对象的 JSON 请求体
• 所有响应以 JSON 返回,Content-Type: application/json

POST/PUT 请求结构

{
  "parameters": {
    "name": "我的徽章",
    "description": "一个示例徽章"
  }
}

请求示例

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": "我的组织",
      "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/ 下的 公开验证端点,允许任何人验证徽章凭证。