Skip to main content
API 密钥用于对 /v1 Public API 的请求进行身份验证。每个密钥都归属于某个服务账号,并在该账号的详情页面中通过 Developer Hub 创建。 如果安全存储和轮换密钥(secret)能够满足贵组织的要求,可为私有后端集成使用限定范围的 API 密钥。无需 OAuth 客户端或令牌交换。如果贵组织要求使用短期有效的 OAuth 访问令牌,请参阅身份验证。

​
密钥的构成

  • 标识符 — 以 ak_ 开头。可以安全地在工单、日志和配置中引用;其本身不具备任何授权。
  • 密钥(Secret) — 以 lsk_live_ 开头。这是您的集成所出示的凭据。它仅在创建或轮换时显示一次,之后无法再次获取。密钥列表仅显示最后四个字符(例如 lsk_live_…xQc4),以便您将列表中的行与调用方持有的凭据进行匹配。
  • 权限 — 所属服务账号权限的一个子集,在创建时选择。密钥的能力永远不会超出其所属账号所允许的范围。
  • 过期时间 — 必填。每个密钥都有过期日期。
密钥(secret)一经显示,请立即将其存储到密钥管理器中。切勿将其提交到版本控制系统、嵌入客户端代码,或通过聊天工具分享。任何持有该密钥的人都可以使用该密钥的权限执行操作。

​
创建密钥

在服务账号的详情页面中,按四个步骤创建密钥:为其命名,选择该密钥具体所需的权限,选择过期时间(30 天、90 天、365 天,或最长一年的自定义时长),然后进行检查。完成后将显示密钥(secret),且仅显示一次。 即使账号允许更多权限,也请将每个密钥的范围限定为其调用方所需的最小权限集。如果密钥泄露,其权限即为影响范围。

​
无停机轮换

轮换会签发新的密钥(secret)并开启一个重叠窗口(1 小时、24 小时或 7 天),在此期间旧密钥仍然有效。这样您可以按自己的节奏将新密钥部署到各个环境中:
1

轮换密钥

选择一个能够覆盖您最慢部署路径的重叠窗口。新密钥仅显示一次,请立即存储。
2

更新您的集成

在所有配置了旧密钥的位置替换为新密钥。在窗口结束之前,该密钥的状态将显示为重叠中。
3

在窗口关闭前进行验证

使用请求日志确认流量已切换到新密钥。重叠期结束后,旧密钥将不再通过身份验证。
也请在到期前进行轮换:接近过期日期的密钥会在密钥列表中被标记为即将过期。已过期的密钥将无法通过身份验证,使用它发出的请求会返回 401,代码为 credential_expired。

​
立即撤销

撤销会立即生效且不可恢复,没有重叠窗口,也无法撤回。一旦怀疑密钥(secret)已暴露,请立即撤销该密钥;如果只是替换一个正常的凭据,则应改为轮换。 使用已撤销的密钥发出的请求会返回 401,代码为 credential_revoked。如果需要一次性停用某个集成持有的所有密钥,请改为禁用其服务账号。