身份认证

每个请求都在 Authorization 请求头中携带 API 密钥：

Authorization: Bearer lp_live_XXXXXXXX…    （工作区密钥）
Authorization: Bearer lpp_live_XXXXXXXX…   （合作伙伴密钥）

密钥在控制台中创建，创建时只显示一次，随后以 SHA-256 哈希形式存储——包括技术支持在内，没有人能找回丢失的密钥。密钥一旦丢失，只能吊销它并创建新的。

密钥类型

• 工作区密钥（lp_live_…）在单个工作区内生效：短链接、数据分析、域名、审计日志和工作区 Webhook。由工作区管理员在 设置 → API 密钥 中创建。
• 合作伙伴密钥（lpp_live_…）作用于合作伙伴账户：客户、套餐、域名、付款、结算和合作伙伴 Webhook。由合作伙伴管理员创建。

工作区密钥调用 /partner/*（反之亦然）会得到 403 forbidden——这两组端点是严格分开的。

权限

权限在创建密钥时逐项授予。请求必须具备其端点所需的每一项权限；缺少哪一项，就会返回 403 insufficient_scope 并在消息中指出缺少的那一项。

| 权限 | 授予的能力 | |---|---| | links:read / links:write | 读取 / 创建、更新、归档、删除短链接 | | analytics:read | 汇总、时间序列、维度拆分、热门链接、CSV 导出，以及合作伙伴范围的点击量总览 | | domains:read / domains:write | 读取 / 接入和断开域名 | | qr:read | 渲染短链接的二维码 | | workspace:read | 工作区资料、限额、审计日志 | | webhooks:read / webhooks:write | 读取 / 管理 Webhook 端点 | | partner:read | 合作伙伴资料、套餐和用量 | | clients:read / clients:write | 读取 / 创建、修改、暂停客户 | | plans:read / plans:write | 读取 / 管理合作伙伴套餐 | | payments:read | 付款镜像与结算记录 |

这就是完整清单——共 15 项权限，密钥只能取用其中的名称。二维码在 API 上是只读的：渲染二维码需要 qr:read，而没有对应的写权限，因为并不存在修改二维码的端点。

有一个搭配常让人踩坑：GET /partner/analytics/overview 需要合作伙伴密钥上的 analytics:read，而不是 partner:read。无论密钥属于哪一类，所有数据分析端点都使用同一项权限。

给每个集成配一个自己的密钥，只授予它必需的最小权限：控制台小组件用的密钥有 links:read + analytics:read 就够了，而开通脚本则需要 clients:write。

套餐限制

API 访问是一项套餐功能（api_access）：

• 对工作区密钥，工作区套餐和合作伙伴的平台套餐都必须包含 API 访问；
• 对合作伙伴密钥，只要合作伙伴的平台套餐包含它即可。

不含 API 访问的套餐会返回 403 plan_restricted。尚未订阅套餐的试用工作区不受此限制。

轮换与吊销

吊销密钥立即生效：下一个请求就会得到 401 unauthorized。要做到零停机轮换，先创建新密钥，把集成切换过去，再吊销旧密钥。每个密钥都会记录 last_used_at，因此吊销之前很容易看出哪个旧密钥已经无人使用。

密钥还可以选填过期日期——过期密钥的行为与被吊销的密钥完全一致。

实践建议

• 密钥属于机密：请存放在密钥管理器中，绝不要写进客户端代码、代码仓库或日志。
• 每个集成一个密钥——吊销其中一个不会影响其他集成，而且审计日志会把每一次变更归到发起它的那个密钥上。