> ## 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 快速入门
> 在 Developer Hub 中创建服务账户和 API 密钥，使用 Basic 身份验证进行身份验证，并向 Living Security Public API 发出您的第一个请求。
在 Developer Hub 中创建服务账户和 API 密钥，然后发出您的第一个请求。本快速入门使用 API 密钥身份验证，您无需 OAuth 客户端。如果您的集成需要短期有效的 OAuth 访问令牌，请参阅[身份验证](/zh-Hans/developers/v1/authentication)。
## 前提条件
* 具有 Living Security 仪表板的管理员访问权限。
* 可在 **设置 → 集成 & Developers → Developer Hub** 下看到 Developer Hub。
## 创建凭据
在 Developer Hub 中，打开 **Service accounts** 选项卡并创建一个账户。为其指定一个具有描述性的名称（例如 `reporting-pipeline`），并授予其密钥可使用的权限——对于本指南，`organization:read` 即已足够。
服务账户的权限是其下创建的每个密钥的权限上限：密钥所能执行的操作绝不会超出其服务账户的允许范围。
打开该服务账户的详细信息页面并创建密钥。选择此特定密钥所需的权限（为该账户权限的子集）以及有效期——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` |
如果您不确定应使用哪个主机，请参阅[区域](/zh-Hans/developers/v1/regions)。将有效密钥发送到另一个区域时，将失败并返回 `unauthorized`。请使用下方示例中的区域下拉菜单切换主机。
从您的机密管理器中加载 `LIVING_SECURITY_API_KEY`，并将其置于发出请求的进程的环境中。下面的示例读取该值，而不会在源代码中嵌入机密值。对于 Python，请先安装 `requests`。
调用 API 时，将机密值放在 HTTP Basic 身份验证的密码或用户名字段中——两者均可，因此要求两个字段都必须填写的客户端（例如 Power BI 的 Web 连接器）可以在另一个字段中填入类似 `apikey` 的占位符。
```bash cURL theme={null}
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"
```
```bash cURL (key as username) theme={null}
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"
```
```python Python theme={null}
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())
```
成功的响应将返回您的组织：
```json Response theme={null}
{
"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`。主机仍必须与该组织所在的区域相匹配。请参阅[区域](/zh-Hans/developers/v1/regions)。
* **按操作检查权限。** 每个 `/v1` 操作都需要一个指定的权限（例如，`GET /v1/organization` 需要 `organization:read`）。缺少该权限的密钥将收到 `403`，代码为 `insufficient_permission`。
* **密钥会过期，并且可以在不中断服务的情况下轮换。** 有关使用重叠窗口进行轮换的信息，请参阅 [API 密钥](/zh-Hans/developers/developer-hub/api-keys)。
## 读取错误响应
每个 `/v1` 错误都是 `application/problem+json`（[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)），并带有稳定的机器可读代码。例如，缺少凭据或凭据未知的请求将返回：
```json 401 Unauthorized theme={null}
{
"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 请求日志相匹配。完整的代码集请参阅[错误参考](/zh-Hans/developers/v1/errors/overview)。
## 契约版本
每个响应都会在 `Living-Security-Version` 标头中回显为其提供服务的契约版本，并同时附带用于关联的 `Request-Id` 标头。
您可以按日期将请求固定到某个已发布的契约版本：
```bash cURL theme={null}
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 更新日志](/zh-Hans/developers/v1/changelog)。
## 排查首次请求的问题
| 结果 | 后续操作 |
| - | - |
| `401 unauthorized` | 检查机密值、其有效期以及组织所在的区域。请勿使用有效凭据尝试其他主机。 |
| `403 insufficient_permission` | 将 `organization:read` 同时授予服务账户及其密钥。 |
| `400 unsupported_version` | 从[更新日志](/zh-Hans/developers/v1/changelog)中选择一个已发布的版本。 |
| `429 rate_limited` | 等待 `Retry-After`；请参照[有界重试示例](/zh-Hans/developers/v1/rate-limits)。 |
| 网络超时 | 检查网络连接，并在应用程序的重试预算范围内重试此读取请求。 |
对于其他错误，请按照响应中的 `doc_url` 操作。请保留 `Request-Id` 以便联系支持团队；切勿在工单中包含 Authorization 标头或您的 API 密钥。
## 后续步骤
为组织选择 US 或 EU 的 `/v1` 主机。
使用 `page_token` 和列表信封遍历列表。
了解请求预算并处理 `429` 响应。
所有错误代码、其 HTTP 状态以及解决方法。
管理服务账户、API 密钥和请求日志。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.