API 快速入門

在 Developer Hub 中建立服務帳戶與 API 金鑰，然後發出您的第一個請求。本快速入門使用 API 金鑰驗證，您不需要 OAuth 用戶端。如果您的整合需要短期有效的 OAuth 存取權杖，請參閱驗證。

先決條件

具備 Living Security 儀表板的管理員存取權限。
可在 設定 → 整合與開發人員 → Developer Hub 下看到 Developer Hub。

建立憑證

建立服務帳戶

在 Developer Hub 中，開啟 服務帳戶 索引標籤並建立帳戶。請為其命名一個具描述性的名稱（例如 reporting-pipeline），並授予其金鑰可使用的權限——就本指南而言，organization:read 即已足夠。帳戶的權限是其下所建立之每個金鑰的上限：金鑰的權限永遠不會超出其服務帳戶所允許的範圍。

建立 API 金鑰

開啟服務帳戶的詳細資料頁面並建立金鑰。請選擇此特定金鑰所需的權限（為帳戶權限的子集）以及到期時間——30 天、90 天或 365 天，或自訂期間。到期時間為必填。金鑰的密鑰以 lsk_live_ 開頭，且僅會顯示一次。請立即將其複製到密鑰管理工具中；日後無法再擷取。

切勿將 API 金鑰密鑰提交至版本控制系統，或嵌入用戶端程式碼中。任何持有該密鑰的人都可以使用該金鑰的權限執行操作。

選擇您的區域

請呼叫與貴組織資料所在地相符的區域 /v1 主機。金鑰僅能在該主機上進行驗證。

區域	基礎 URL
美國	`https://api.us-east-1.livingsecurity.ai/v1`
歐盟	`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 的 請求記錄 索引標籤中。

使用相同密鑰的 Bearer 驗證（Authorization: Bearer lsk_live_...）同樣可行。提供 Basic 驗證，是為了讓僅支援使用者名稱／密碼的工具（例如 Power BI 的 Web 連接器）能夠連線。

驗證的運作方式

憑證決定組織。 /v1 請求不帶有租用戶選擇器：沒有組織路徑區段，也沒有組織標頭。傳送 x-organization-id 標頭會被拒絕，並傳回 invalid_request。主機仍必須與該組織的區域相符。請參閱區域。
權限依每項操作進行檢查。 每項 /v1 操作都需要具名權限（例如，GET /v1/organization 需要 organization:read）。缺少該權限的金鑰會收到帶有代碼 insufficient_permission 的 403。
金鑰會到期，且可在不中斷服務的情況下輪替。 如需了解具重疊時段的輪替方式，請參閱 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"

版本解析順序如下：若請求標頭存在則使用之，否則使用服務帳戶固定的預設值，再否則使用最新的已發布版本。請求未發布（或已過停用日期）的版本時，會傳回帶有代碼 unsupported_version 的 400。已發布的版本及其變更列於 API 變更記錄。

疑難排解您的第一個請求

結果	後續動作
`401 unauthorized`	檢查密鑰、其到期時間以及組織的區域。請勿使用有效憑證嘗試其他主機。
`403 insufficient_permission`	將 `organization:read` 同時授予服務帳戶及其金鑰。
`400 unsupported_version`	從變更記錄中選擇已發布的版本。
`429 rate_limited`	等待 `Retry-After`；請遵循有限重試範例。
網路逾時	檢查連線狀況，並在應用程式的重試預算內重試此讀取操作。

若發生其他錯誤，請依照回應中的 doc_url 處理。請保留 Request-Id 以供支援團隊使用；切勿在支援單中包含 Authorization 標頭或您的 API 金鑰。

後續步驟

區域

為組織選擇美國或歐盟的 /v1 主機。

分頁

使用 page_token 與清單封裝逐頁瀏覽清單。

速率限制

了解請求預算並處理 429 回應。

錯誤參考

所有錯誤代碼、其 HTTP 狀態以及解決方式。

Developer Hub

管理服務帳戶、API 金鑰與請求記錄。

開發人員中心

公開 API v1

API v1 參考

先決條件

建立憑證

驗證的運作方式

讀取錯誤回應

合約版本

疑難排解您的第一個請求

後續步驟

區域

分頁

速率限制

錯誤參考

Developer Hub

開發人員中心

公開 API v1

API v1 參考

​先決條件

​建立憑證

​驗證的運作方式

​讀取錯誤回應

​合約版本

​疑難排解您的第一個請求

​後續步驟

區域

分頁

速率限制

錯誤參考

Developer Hub

先決條件

建立憑證

驗證的運作方式

讀取錯誤回應

合約版本

疑難排解您的第一個請求

後續步驟