API 密钥

API 密钥让你能够以编程方式访问 badges.ninja REST API。你可以用它们在自己的应用中自动完成徽章的创建、颁发和管理。

创建 API 密钥

1. 从侧边栏打开 API Keys 页面。
2. 点击 Create API Key，会打开一个内联表单：

3. 为密钥命名并点击 Create。完整密钥会在绿色横幅中显示一次：

4. 请立即复制密钥——完整密钥只会显示一次。如果丢失，你需要创建新的密钥。关闭横幅后，控制台只会显示密钥的前缀（例如 bws_a1b2c3d4...）；完整密钥保存在服务器端，用于验证你的请求：

每一行还会显示密钥的创建时间，并在密钥被使用后显示 last used 时间戳，方便你发现闲置的密钥。

访问范围

创建密钥时，你可以将其设为只读，也可以保留完全访问权限：

范围	允许的操作
完全访问（默认）	读取和写入——列出数据，以及创建、颁发、更新或删除。
只读	仅限安全的 GET 请求。任何会修改数据的请求（POST、PUT、PATCH、DELETE）都会被拒绝，并返回 403 Forbidden。

对于只需要读取数据的集成（报表、仪表盘、备份），请使用只读密钥，这样即使密钥泄露也无法更改任何内容。在创建表单中勾选 Read-only key；只读密钥会在列表中显示 Read-only 标记。在引入访问范围之前创建的密钥仍保留完全访问权限。

密钥格式

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 Keys 页面。
2. 找到要删除的密钥。
3. 点击 Delete。
4. 确认删除。

密钥一经删除便立即失效。所有使用该密钥的应用都会收到验证错误。