API 密钥

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

创建 API 密钥

1. 在侧边栏打开 API 密钥 页面。
2. 点击 创建 API 密钥,内嵌表单打开:

3. 给密钥起个名字并点击 创建。完整密钥会在绿色横幅上 仅显示一次:

4. 请立刻复制密钥 — 完整密钥只会 显示 一次。一旦丢失,必须重新创建。关闭横幅后,仪表板将只会显示密钥的前缀(例如 bws_a1b2c3d4...);完整密钥会保存在服务端,用于对你的请求进行认证:

每一行还会显示密钥的创建时间,以及在密钥被使用过后显示 最后使用 时间戳,方便你发现闲置的密钥。

访问范围

创建密钥时,你可以将其设为 只读,或保留为完全访问:

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

对于只需要 读取 你数据的集成(报表、仪表板、备份),请使用只读密钥,这样即使密钥泄露也无法更改任何内容。在创建表单中勾选 只读密钥;只读密钥会在列表中显示 只读 标记。在访问范围功能出现之前创建的密钥保留完全访问。

密钥格式

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 美元/月)	5
Pro(29 美元/月)	20

密钥过期

每个 API 密钥都会在 创建一年后过期。密钥一旦过期就会停止对请求进行认证,效果与被删除完全相同。请在旧密钥失效之前创建新密钥,以避免中断。

删除密钥

1. 打开 API 密钥 页面。
2. 找到要删除的密钥。
3. 点击 删除。
4. 确认删除。

删除后,密钥立即失效。仍在使用该密钥的任何应用都会收到认证错误。