> ## 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-Hant/developers/v1/authentication)。

## 先決條件

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

## 建立憑證

<Steps>
  <Step title="建立服務帳戶">
    在 Developer Hub 中，開啟 **服務帳戶** 索引標籤並建立帳戶。請為其命名一個具描述性的名稱（例如 `reporting-pipeline`），並授予其金鑰可使用的權限——就本指南而言，`organization:read` 即已足夠。

    帳戶的權限是其下所建立之每個金鑰的上限：金鑰的權限永遠不會超出其服務帳戶所允許的範圍。
  </Step>

  <Step title="建立 API 金鑰">
    開啟服務帳戶的詳細資料頁面並建立金鑰。請選擇此特定金鑰所需的權限（為帳戶權限的子集）以及到期時間——30 天、90 天或 365 天，或自訂期間。到期時間為必填。

    金鑰的密鑰以 `lsk_live_` 開頭，且僅會顯示**一次**。請立即將其複製到密鑰管理工具中；日後無法再擷取。

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

  <Step title="選擇您的區域">
    請呼叫與貴組織資料所在地相符的區域 `/v1` 主機。金鑰僅能在該主機上進行驗證。

    | 區域 | 基礎 URL |
    | - | - |
    | 美國 | `https://api.us-east-1.livingsecurity.ai/v1` |
    | 歐盟 | `https://api.eu-west-1.livingsecurity.ai/v1` |

    如果您不確定應使用哪個主機，請參閱[區域](/zh-Hant/developers/v1/regions)。將有效金鑰傳送至另一個區域時，會以 `unauthorized` 失敗。請使用下方範例中的區域下拉式選單切換主機。
  </Step>

  <Step title="發出您的第一個請求">
    從密鑰管理工具載入 `LIVING_SECURITY_API_KEY` 至發出請求之處理程序的環境中。下方範例會讀取該值，而不會在原始程式碼中嵌入密鑰。若使用 Python，請先安裝 `requests`。

    呼叫 API 時，請將密鑰放在 HTTP Basic 驗證的密碼或使用者名稱欄位中——兩者皆可，因此需要兩個欄位都填寫的用戶端（例如 Power BI 的 Web 連接器）可在另一個欄位中放入預留位置，例如 `apikey`。

    <CodeGroup>
      ```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())
      ```
    </CodeGroup>

    成功的回應會傳回您的組織：

    ```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"
    }
    ```

    <Check>
      如果您收到此回應，表示您的憑證可正常運作。該請求也會在片刻內顯示於 Developer Hub 的 **請求記錄** 索引標籤中。
    </Check>
  </Step>
</Steps>

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

## 驗證的運作方式

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

## 合約版本

每個回應都會在 `Living-Security-Version` 標頭中回傳處理該請求的合約版本，並附帶用於關聯比對的 `Request-Id` 標頭。

您可以依日期將請求固定至已發布的合約版本：

<CodeGroup>
  ```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"
  ```
</CodeGroup>

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

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

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

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

## 後續步驟

<CardGroup cols={2}>
  <Card title="區域" href="/zh-Hant/developers/v1/regions">
    為組織選擇美國或歐盟的 `/v1` 主機。
  </Card>

  <Card title="分頁" href="/zh-Hant/developers/v1/pagination">
    使用 `page_token` 與清單封裝逐頁瀏覽清單。
  </Card>

  <Card title="速率限制" href="/zh-Hant/developers/v1/rate-limits">
    了解請求預算並處理 `429` 回應。
  </Card>

  <Card title="錯誤參考" href="/zh-Hant/developers/v1/errors/overview">
    所有錯誤代碼、其 HTTP 狀態以及解決方式。
  </Card>

  <Card title="Developer Hub" href="/zh-Hant/developers/developer-hub/overview">
    管理服務帳戶、API 金鑰與請求記錄。
  </Card>
</CardGroup>


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