API 密钥和访问令牌

API 密钥是你的程序进入 LinkHarbor API 的凭证。它属于工作区，而不属于某个人，并且只能做你通过权限范围允许的事。实际调用时，你要用密钥换取一个短期有效的访问令牌。

#谁可以创建 API 密钥？

• 工作区的所有者和管理员；编辑者和查看者在“回调与 API”中只能看到“已连接的应用”卡片
• Creator Pro 起提供；在 Creator Free 中，卡片上显示“API 密钥自 Creator Pro 起提供。”
• 可同时启用的密钥数：Creator Pro 最多 5 个，Creator Agency 最多 20 个，Enterprise 最多 50 个

达到上限后，创建密钥会以 409 limit_reached 失败。请先删除一个不再需要的密钥。

#创建 API 密钥

1. 在导航中打开“回调与 API”
2. 在“API 密钥”卡片中点击“+ 创建新密钥”
3. 在“名称（可选）”中输入一个以后便于识别的名称，例如“CI/CD 流水线”或“商店同步”
4. 在“权限范围”中为每个领域选择“读取”或“写入”
5. 点击“创建密钥”
6. 立即复制“密钥（私密）”并妥善保存
7. 关闭对话框；你随时可以在列表中找到密钥 ID

“名称（可选）”

最多 64 个字符。没有名称时，密钥在列表中显示为“API 密钥 #ID”。

“权限范围”

至少需要选择一个。“写入”会自动包含同一领域的“读取”。统计和支持者付款只能读取，工作区模板只能写入。所有权限范围的说明请参阅权限范围详解。

“密钥（私密）”

以 lt_ 开头，只显示一次（“⚠️ 仅显示一次，请立即复制！”）。LinkHarbor 只保存它的哈希值，以后无法再次显示给你。

“密钥 ID：”

16 个字符，由数字和大写字母 A–F 组成，例如 6F668EA6598B0692。它不是机密，会显示在列表中，并带有复制按钮。

#密钥列表

每个已启用的密钥都会显示名称、状态“已启用”、密钥 ID、权限范围、“创建于：”以及“最后使用：”或“尚未使用”。每次用该密钥调用时都会更新最后使用时间，但最多每分钟更新一次。“↺ 刷新”会重新加载列表。

#用密钥换取访问令牌

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

访问令牌。每次请求都以 Authorization: Bearer <token> 的形式发送它。

expires_in

有效期（秒）：900，即 15 分钟。没有刷新令牌；令牌过期后，只需用密钥 ID 和密钥重新获取一个。

令牌代表工作区，并带有与密钥完全相同的权限范围。它不像人那样拥有角色：控制台中只限所有者和管理员使用的端点（成员、账单、管理域名、Webhook、工作区设置）始终会拒绝来自 API 密钥的令牌。例外的是短链接和工作区模板（有对应的权限范围即可使用），以及用 read:workspaces 读取回调密钥（不含明文密钥）。

#失败尝试和锁定

出现 api_key_locked 时，剩余时间在 details.retry_after_sec 中。成功换取一次令牌后，计数器会重置。

#删除和替换密钥

1. 点击密钥旁边的“删除”
2. 输入 DELETE 进行确认
3. 点击“永久删除”

密钥会立即失效，已经签发的访问令牌也会从这一刻起失效，并收到 401 invalid_token。没有轮换按钮。要更换密钥，请先创建新密钥，把你的程序切换过去，然后删除旧密钥。

#套餐降级时

如果工作区降级到 Creator Free，所有 API 密钥都会被撤销。如果降级到允许密钥数更少的套餐，会保留最新的密钥，其余的被撤销。被撤销的密钥在之后升级时不会恢复，届时你需要创建新的密钥。所有者会收到一封列出已停用功能的邮件。更多信息请参阅取消订阅、降级和付款失败。

#安全保管

• 只把密钥保存在密钥管理工具或环境变量中，绝不要放进源代码或 Git 仓库
• 绝不要在浏览器中运行的代码里或用户设备上的应用中使用它
• 为每个应用创建单独的密钥，并只给尽可能少的权限范围
• 不再需要的密钥立即删除
• 如果怀疑密钥泄露：删除它并创建一个新的