> ## 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

> 维护通过 API 访问密钥换取持有者令牌的现有 /api/v1 集成。

本指南适用于通过 API 访问密钥换取持有者令牌的现有 `/api/v1` 集成。这些集成的凭据和请求格式与 `/v1` 公共 API 不同。

如需创建新的集成，请从 [API 快速入门](/zh-Hans/developers/v1/quickstart)和[身份验证](/zh-Hans/developers/v1/authentication)开始。新的 `/v1` API 使用服务账号 API 密钥或 OAuth 访问令牌。

## 开始之前

您需要具备：

* 允许管理 API 访问密钥的 Living Security 访问权限
* 在 **设置 → Access Keys** 下创建的 API 访问密钥
* 创建凭据时显示的一次性访问密钥私密值
* Living Security 随您的公共 API 凭据一同提供的 API 颁发者 ID
* 您要集成的组织所对应的区域基础 URL
* 服务器端运行环境和密钥管理器

访问密钥私密值不得放置在浏览器代码、移动应用、源代码管理、客户端环境变量、工单或共享日志中。

<Note>
  Access Keys 对话框会显示一次性私密值，但不会显示 API 颁发者 ID。如果 Living Security 没有随您的公共 API 凭据提供颁发者 ID，请向 [Living Security 支持团队](mailto:support@livingsecurity.com)申请。颁发者 ID 不是访问密钥 ID 或组织 ID。
</Note>

## 区域主机

旧版契约使用以下区域 `/api/v1` 生产主机：

| 区域 | 基础 URL |
| - | - |
| 美国 | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| 欧盟 | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

请使用分配给 Living Security 组织的区域。请勿为规避授权或可用性错误而切换区域。

## 旧版资源

| 资源 | 支持的操作 |
| - | - |
| **人** | 搜索组织中的人员并检索某个人员的成员关系 |
| **API 访问密钥** | 创建、列出、轮换和撤销 API 访问密钥 |

请使用 **Developers → Public API Reference** 查看完整的操作、参数、请求、响应和架构列表。如果某项操作不在其中，则它目前不属于公共 API。

## 身份验证

公共 API 访问分为两个阶段：

1. 使用私密访问密钥和 API 颁发者 ID 换取短期有效的持有者令牌和组织 ID。
2. 在每个 API 请求中发送持有者令牌和组织 ID。

所需的请求标头如下：

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

组织标头必须是访问密钥交换所返回的组织。密钥不会授权访问任意组织 ID。

### TypeScript SDK

安装当前主版本：

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

然后交换密钥并配置 SDK：

```typescript theme={null}
import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});
```

对于欧盟组织，请使用欧盟基础 URL。SDK 交换适用于服务器端 Node.js 运行环境。

### 直接 REST 请求

如果您在 SDK 之外执行交换，请在每个请求中发送其持有者令牌和组织 ID：

```bash theme={null}
curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"
```

持有者令牌的有效期很短。获取新令牌时，请重新交换访问密钥，而不要将持有者令牌作为永久凭据保存。

## 访问密钥生命周期

* 以所属集成或自动化的名称命名密钥。
* 选择访问密钥表单提供的最小权限范围。
* 立即保存一次性私密值；创建或轮换之后无法再次获取。
* 通过 **设置 → Access Keys** 轮换密钥，并在撤销旧凭据之前部署替换密钥。
* 撤销不再使用或私密值可能已泄露的密钥。
* 如果您的组织可使用服务账号密钥类型，请将其用于非人工集成。

## 分页

人员搜索支持 `limit`、`cursor`、`offset` 和 `includeTotal` 参数。按顺序遍历时，建议使用上一次响应返回的游标。

* `limit` 默认为 50，可接受 1–100。
* `cursor` 从上一次响应继续。
* `offset` 跳过指定数量的记录，默认为 0。
* `includeTotal=true` 请求精确的筛选后计数；不需要计数时请省略。

请读取端点返回的 `pagination` 对象。请勿根据收到的行数计算下一页，也不要合并独立分页的请求后自行对部分结果排序。

## 错误

文档中说明的 JSON 错误通常采用以下格式：

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

`message` 可以是字符串，也可以是验证消息数组。

| 状态 | 含义 | 响应 |
| - | - | - |
| `400` | 参数或请求正文无效 | 更正指出的验证错误 |
| `401` | 持有者令牌缺失、无效或已过期 | 重新交换访问密钥并重试一次 |
| `403` | 凭据缺少权限或组织访问权限 | 检查密钥权限范围和组织上下文 |
| `404` | 资源在已授权的组织中不存在 | 核实资源 ID 和组织 |
| `408` | 请求超时 | 使用有限的指数退避进行重试 |
| `429` | 已达到速率限制 | 等待时间至少与 `Retry-After` 相同（如果存在） |
| `5xx` | 临时服务故障 | 使用有限的指数退避重试安全的读取操作 |

当前整理的契约并未发布统一的数值速率限制，也不保证每个操作都返回请求 ID 响应标头。请求支持时，请提供 UTC 时间、方法、路径、状态以及已脱敏的响应正文。

除非操作明确说明具有幂等性，否则请勿自动重试创建、轮换、撤销或删除操作。出现不明确的网络故障后，请检查资源的当前状态。

## 兼容性与弃用

V1 默认以增量方式演进。客户端必须忽略未知的响应字段。重大变更需要提供文档化的迁移路径；已弃用的操作会保留在参考文档中，并在迁移期内说明弃用原因、可用的替代方案和终止日期。

请将 SDK 固定在兼容的主版本，并在升级前查看其发行说明。请以生成的公共 API 参考（而非第一方应用客户端）作为架构的权威来源。

## 公共 API、MCP 与 Web 应用程序

| 接口 | 用途 | 兼容性模型 |
| - | - | - |
| **公共 API** | 客户系统、合作伙伴和外部自动化 | 稳定的版本化资源 |
| **MCP** | 经授权的 AI 工具交互 | 工具契约和紧凑的结构化输出 |
| **Web 应用程序** | Living Security 产品中的人工工作流程 | 由应用负责的契约，可能随 UI 演进 |

如需将 AI 工具连接到 Living Security，请参阅 [MCP 集成](/zh-Hans/integrations/mcp)。

## 获取帮助

请联系 [Living Security 支持团队](mailto:support@livingsecurity.com)，并提供：

* 组织和区域
* SDK 名称和版本（如使用）
* UTC 时间戳、方法和路径
* HTTP 状态和已脱敏的错误正文

切勿包含访问密钥私密值、持有者令牌或私密的客户数据。

## 相关内容

<CardGroup cols={2}>
  <Card title="API 访问密钥" icon="key" href="/zh-Hans/integrations/api-keys">
    创建、轮换和撤销 API 凭据。
  </Card>

  <Card title="MCP 集成" icon="robot" href="/zh-Hans/integrations/mcp">
    通过 Model Context Protocol 连接受支持的 AI 工具。
  </Card>
</CardGroup>


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