API 快速入门

在 Developer Hub 中创建服务账户和 API 密钥，然后发出您的第一个请求。本快速入门使用 API 密钥身份验证，您无需 OAuth 客户端。如果您的集成需要短期有效的 OAuth 访问令牌，请参阅身份验证。

前提条件

具有 Living Security 仪表板的管理员访问权限。
可在 设置 → 集成 & Developers → Developer Hub 下看到 Developer Hub。

创建凭据

创建服务账户

在 Developer Hub 中，打开 Service accounts 选项卡并创建一个账户。为其指定一个具有描述性的名称（例如 reporting-pipeline），并授予其密钥可使用的权限——对于本指南，organization:read 即已足够。服务账户的权限是其下创建的每个密钥的权限上限：密钥所能执行的操作绝不会超出其服务账户的允许范围。

创建 API 密钥

打开该服务账户的详细信息页面并创建密钥。选择此特定密钥所需的权限（为该账户权限的子集）以及有效期——30 天、90 天或 365 天，或自定义时长。有效期为必填项。密钥的机密值以 lsk_live_ 开头，且仅显示一次。请立即将其复制到机密管理器中；之后无法再次获取。

切勿将 API 密钥的机密值提交到版本控制系统，也不要将其嵌入客户端代码。任何持有该机密值的人都可以使用该密钥的权限执行操作。

选择您的区域

请调用与组织数据驻留位置相匹配的区域 /v1 主机。密钥仅能在该主机上通过身份验证。

区域	基础 URL
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

如果您不确定应使用哪个主机，请参阅区域。将有效密钥发送到另一个区域时，将失败并返回 unauthorized。请使用下方示例中的区域下拉菜单切换主机。

发出您的第一个请求

从您的机密管理器中加载 LIVING_SECURITY_API_KEY，并将其置于发出请求的进程的环境中。下面的示例读取该值，而不会在源代码中嵌入机密值。对于 Python，请先安装 requests。调用 API 时，将机密值放在 HTTP Basic 身份验证的密码或用户名字段中——两者均可，因此要求两个字段都必须填写的客户端（例如 Power BI 的 Web 连接器）可以在另一个字段中填入类似 apikey 的占位符。

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

成功的响应将返回您的组织：

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

如果您收到此响应，则说明您的凭据有效。该请求也会在片刻之内显示在 Developer Hub 的 Request logs 选项卡中。

使用相同机密值的 Bearer 身份验证（Authorization: Bearer lsk_live_...）同样有效。提供 Basic 身份验证是为了让仅支持用户名/密码的工具（如 Power BI 的 Web 连接器）能够连接。

身份验证的工作原理

凭据决定组织。 /v1 请求不带租户选择器：没有组织路径段，也没有组织标头。发送 x-organization-id 标头会被拒绝，并返回 invalid_request。主机仍必须与该组织所在的区域相匹配。请参阅区域。
按操作检查权限。 每个 /v1 操作都需要一个指定的权限（例如，GET /v1/organization 需要 organization:read）。缺少该权限的密钥将收到 403，代码为 insufficient_permission。
密钥会过期，并且可以在不中断服务的情况下轮换。 有关使用重叠窗口进行轮换的信息，请参阅 API 密钥。

读取错误响应

每个 /v1 错误都是 application/problem+json（RFC 9457），并带有稳定的机器可读代码。例如，缺少凭据或凭据未知的请求将返回：

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

请基于 code 进行分支处理，切勿基于 detail。请按照 doc_url 中的解决步骤操作，并在联系支持团队时提供 request_id——它与 Request-Id 响应标头及 Developer Hub 请求日志相匹配。完整的代码集请参阅错误参考。

契约版本

每个响应都会在 Living-Security-Version 标头中回显为其提供服务的契约版本，并同时附带用于关联的 Request-Id 标头。您可以按日期将请求固定到某个已发布的契约版本：

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

版本按以下顺序解析：若请求标头存在，则使用请求标头；否则使用服务账户固定的默认版本；再否则使用最新发布的版本。请求未发布（或已过停用日期）的版本时，将返回 400，代码为 unsupported_version。已发布的版本及其变更列于 API 更新日志。

排查首次请求的问题

结果	后续操作
`401 unauthorized`	检查机密值、其有效期以及组织所在的区域。请勿使用有效凭据尝试其他主机。
`403 insufficient_permission`	将 `organization:read` 同时授予服务账户及其密钥。
`400 unsupported_version`	从更新日志中选择一个已发布的版本。
`429 rate_limited`	等待 `Retry-After`；请参照有界重试示例。
网络超时	检查网络连接，并在应用程序的重试预算范围内重试此读取请求。

对于其他错误，请按照响应中的 doc_url 操作。请保留 Request-Id 以便联系支持团队；切勿在工单中包含 Authorization 标头或您的 API 密钥。

后续步骤

区域

为组织选择 US 或 EU 的 /v1 主机。

分页

使用 page_token 和列表信封遍历列表。

速率限制

了解请求预算并处理 429 响应。

错误参考

所有错误代码、其 HTTP 状态以及解决方法。

Developer Hub

管理服务账户、API 密钥和请求日志。

开发者中心

公共 API v1

API v1 参考

前提条件

创建凭据

身份验证的工作原理

读取错误响应

契约版本

排查首次请求的问题

后续步骤

区域

分页

速率限制

错误参考

Developer Hub

开发者中心

公共 API v1

API v1 参考

​前提条件

​创建凭据

​身份验证的工作原理

​读取错误响应

​契约版本

​排查首次请求的问题

​后续步骤

区域

分页

速率限制

错误参考

Developer Hub

前提条件

创建凭据

身份验证的工作原理

读取错误响应

契约版本

排查首次请求的问题

后续步骤