舊版公開 API - Living Security Platform

本指南適用於現有的 /api/v1 整合，這類整合會以 API 存取金鑰交換持有者權杖（bearer token）。其憑證與請求格式與 /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
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 存取分為兩個階段：

以密鑰存取金鑰與 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,
});

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

介面	用途	相容性模式
公開 API	客戶系統、合作夥伴與外部自動化	穩定且具版本的資源
MCP	具權限控管的 AI 工具互動	工具合約與精簡的結構化輸出
網頁應用程式	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 與網頁應用程式

​取得協助

​相關資源

API 存取金鑰

MCP 整合

開始之前

區域主機

舊版資源

驗證

TypeScript SDK

直接 REST 請求

存取金鑰生命週期

分頁

錯誤

相容性與淘汰

公開 API、MCP 與網頁應用程式

取得協助

相關資源