> ## 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 存取金鑰交換持有者權杖（bearer token）的 /api/v1 整合。

本指南適用於現有的 `/api/v1` 整合，這類整合會以 API 存取金鑰交換持有者權杖（bearer token）。其憑證與請求格式與 `/v1` 公開 API 不同。

若要建立新的整合，請從 [API 快速入門](/zh-Hant/developers/v1/quickstart)與[驗證](/zh-Hant/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 |
| - | - |
| US | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| EU | `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,
});
```

EU 組織請使用 EU 基礎 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 與網頁應用程式

| 介面 | 用途 | 相容性模式 |
| - | - | - |
| **公開 API** | 客戶系統、合作夥伴與外部自動化 | 穩定且具版本的資源 |
| **MCP** | 具權限控管的 AI 工具互動 | 工具合約與精簡的結構化輸出 |
| **網頁應用程式** | Living Security 產品中的人工作業流程 | 由應用程式擁有、可能隨 UI 演進的合約 |

若要將 AI 工具連線至 Living Security，請參閱 [MCP 整合](/zh-Hant/integrations/mcp)。

## 取得協助

請聯絡 [Living Security 支援團隊](mailto:support@livingsecurity.com)，並提供：

* 組織與區域
* 若有使用，請提供 SDK 名稱與版本
* UTC 時間戳記、方法與路徑
* HTTP 狀態與已清除敏感資訊的錯誤本文

請勿提供存取金鑰密鑰、持有者權杖或私密的客戶資料。

## 相關資源

<CardGroup cols={2}>
  <Card title="API 存取金鑰" icon="key" href="/zh-Hant/integrations/api-keys">
    建立、輪替及撤銷 API 憑證。
  </Card>

  <Card title="MCP 整合" icon="robot" href="/zh-Hant/integrations/mcp">
    透過 Model Context Protocol 連線至支援的 AI 工具。
  </Card>
</CardGroup>


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