> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥

> 创建、轮换和撤销用于对 Living Security Public API 请求进行身份验证的凭据。

API 密钥用于对 `/v1` Public API 的请求进行身份验证。每个密钥都归属于某个[服务账号](/zh-Hans/developers/developer-hub/service-accounts),并在该账号的详情页面中通过 [Developer Hub](/zh-Hans/developers/developer-hub/overview) 创建。

如果安全存储和轮换密钥(secret)能够满足贵组织的要求,可为私有后端集成使用限定范围的 API 密钥。无需 OAuth 客户端或令牌交换。如果贵组织要求使用短期有效的 OAuth 访问令牌,请参阅[身份验证](/zh-Hans/developers/v1/authentication)。

## 密钥的构成

* **标识符** — 以 `ak_` 开头。可以安全地在工单、日志和配置中引用;其本身不具备任何授权。
* **密钥(Secret)** — 以 `lsk_live_` 开头。这是您的集成所出示的凭据。它仅在创建或轮换时显示**一次**,之后无法再次获取。密钥列表仅显示最后四个字符(例如 `lsk_live_…xQc4`),以便您将列表中的行与调用方持有的凭据进行匹配。
* **权限** — 所属服务账号权限的一个子集,在创建时选择。密钥的能力永远不会超出其所属账号所允许的范围。
* **过期时间** — 必填。每个密钥都有过期日期。

<Warning>
  密钥(secret)一经显示,请立即将其存储到密钥管理器中。切勿将其提交到版本控制系统、嵌入客户端代码,或通过聊天工具分享。任何持有该密钥的人都可以使用该密钥的权限执行操作。
</Warning>

## 创建密钥

在服务账号的详情页面中,按四个步骤创建密钥:为其命名,选择该密钥具体所需的权限,选择过期时间(30 天、90 天、365 天,或最长一年的自定义时长),然后进行检查。完成后将显示密钥(secret),且仅显示一次。

即使账号允许更多权限,也请将每个密钥的范围限定为其调用方所需的最小权限集。如果密钥泄露,其权限即为影响范围。

## 无停机轮换

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

<Steps>
  <Step title="轮换密钥">
    选择一个能够覆盖您最慢部署路径的重叠窗口。新密钥仅显示一次,请立即存储。
  </Step>

  <Step title="更新您的集成">
    在所有配置了旧密钥的位置替换为新密钥。在窗口结束之前,该密钥的状态将显示为重叠中。
  </Step>

  <Step title="在窗口关闭前进行验证">
    使用[请求日志](/zh-Hans/developers/developer-hub/request-logs)确认流量已切换到新密钥。重叠期结束后,旧密钥将不再通过身份验证。
  </Step>
</Steps>

也请在到期前进行轮换:接近过期日期的密钥会在密钥列表中被标记为即将过期。已过期的密钥将无法通过身份验证,使用它发出的请求会返回 `401`,代码为 [`credential_expired`](/zh-Hans/developers/v1/errors/credential_expired)。

## 立即撤销

撤销会立即生效且不可恢复,没有重叠窗口,也无法撤回。一旦怀疑密钥(secret)已暴露,请立即撤销该密钥;如果只是替换一个正常的凭据,则应改为轮换。

使用已撤销的密钥发出的请求会返回 `401`,代码为 [`credential_revoked`](/zh-Hans/developers/v1/errors/credential_revoked)。如果需要一次性停用某个集成持有的所有密钥,请改为禁用其服务账号。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.