认证

所有发往 badges.ninja 的 API 请求都需要认证。本页说明如何对你的请求进行认证。

基础 URL

https://api.badges.ninja

所有 API 端点都相对于此基础 URL。

API 密钥认证

主要的认证方式是在 X-Api-Key 头中传递 API 密钥。

获取 API 密钥

通过控制台:

1. 登录 badges.ninja。
2. 在侧边栏中进入 API Keys。
3. 点击 Create API Key。
4. 复制密钥(密钥只显示一次)。

通过 API:

也可以使用 Cognito 认证流程获得的 JWT 令牌,通过 API 管理 API 密钥。最简单的方式是使用控制台。

使用 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 请求发送包含 parameters 对象的 JSON 请求体
• 所有响应都返回 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"
    }
  }'

响应示例

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

公开端点

部分端点无需认证。它们是 /certify-badge/ 下的 公开验证端点,允许任何人验证徽章凭证。