旧版公共 API - Living Security Platform

本指南适用于通过 API 访问密钥换取持有者令牌的现有 /api/v1 集成。这些集成的凭据和请求格式与 /v1 公共 API 不同。如需创建新的集成，请从 API 快速入门和身份验证开始。新的 /v1 API 使用服务账号 API 密钥或 OAuth 访问令牌。

开始之前

您需要具备：

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

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

Access Keys 对话框会显示一次性私密值，但不会显示 API 颁发者 ID。如果 Living Security 没有随您的公共 API 凭据提供颁发者 ID，请向 Living Security 支持团队申请。颁发者 ID 不是访问密钥 ID 或组织 ID。

区域主机

旧版契约使用以下区域 /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 访问分为两个阶段：

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

所需的请求标头如下：

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

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

TypeScript SDK

安装当前主版本：

npm install @livingsecurity/sdk@^1

然后交换密钥并配置 SDK：

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：

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 错误通常采用以下格式：

{
  "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 集成。

获取帮助

请联系 Living Security 支持团队，并提供：

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

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

API 访问密钥

创建、轮换和撤销 API 凭据。

MCP 集成

通过 Model Context Protocol 连接受支持的 AI 工具。

公共 API

公共 API 参考

​开始之前

​区域主机

​旧版资源

​身份验证

​TypeScript SDK

​直接 REST 请求

​访问密钥生命周期

​分页

​错误

​兼容性与弃用

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

​获取帮助

​相关内容

API 访问密钥

MCP 集成

开始之前

区域主机

旧版资源

身份验证

TypeScript SDK

直接 REST 请求

访问密钥生命周期

分页

错误

兼容性与弃用

公共 API、MCP 与 Web 应用程序

获取帮助

相关内容