> ## 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 金鑰

> 建立、輪替及撤銷用於驗證 Living Security Public API 請求的憑證。

API 金鑰用於驗證對 `/v1` Public API 的請求。每個金鑰都隸屬於某個[服務帳戶](/zh-Hant/developers/developer-hub/service-accounts),並且是在該帳戶的詳細資料頁面中,透過[開發人員中心](/zh-Hant/developers/developer-hub/overview)建立。

當您能夠安全地儲存並輪替密鑰,且符合貴組織的要求時,請為私有後端整合使用限定範圍的 API 金鑰。此方式無需 OAuth 用戶端或權杖交換。若貴組織要求改用短效的 OAuth 存取權杖,請參閱[驗證](/zh-Hant/developers/v1/authentication)。

## 金鑰的組成

* **標識符** — 以 `ak_` 開頭。可安全地在工單、記錄檔和設定中引用;其本身不具任何授權效力。
* **密鑰** — 以 `lsk_live_` 開頭。這是您的整合所出示的憑證。密鑰僅會在建立或輪替時顯示**一次**,之後無法再擷取。金鑰清單僅顯示最後四個字元(例如 `lsk_live_…xQc4`),以便您將清單中的資料列與呼叫端持有的憑證對應。
* **權限** — 擁有者服務帳戶之權限的子集,於建立時選定。金鑰所能執行的操作絕不會超出其帳戶所允許的範圍。
* **到期日** — 必填。每個金鑰都有到期日期。

<Warning>
  密鑰一經顯示,請立即存放至密鑰管理工具中。切勿將其提交至版本控制系統、嵌入用戶端程式碼,或透過聊天工具分享。任何持有該密鑰的人,都能以該金鑰的權限執行操作。
</Warning>

## 建立金鑰

在服務帳戶的詳細資料頁面中,透過四個步驟建立金鑰:命名、選擇此特定金鑰所需的權限、選擇到期日(30 天、90 天、365 天,或最長一年的自訂期間),然後進行檢閱。完成後會顯示密鑰,且僅顯示一次。

請將每個金鑰的範圍限定為其呼叫端所需的最小權限集合,即使帳戶允許更多權限亦然。若金鑰外洩,其權限即為受影響的範圍。

## 無停機輪替

輪替會核發新的密鑰,並啟動一段重疊期間(1 小時、24 小時或 7 天),在此期間**舊密鑰仍可繼續使用**。這讓您能依自己的步調,將新密鑰逐步部署到各個環境:

<Steps>
  <Step title="輪替金鑰">
    請選擇足以涵蓋最慢部署路徑的重疊期間。新密鑰僅顯示一次,請立即存放。
  </Step>

  <Step title="更新您的整合">
    在所有設定了舊密鑰的位置替換為新密鑰。在重疊期間結束前,金鑰的狀態會顯示為重疊中。
  </Step>

  <Step title="在重疊期間結束前進行驗證">
    請使用[請求記錄](/zh-Hant/developers/developer-hub/request-logs)確認流量已切換至新密鑰。重疊期間結束後,舊密鑰將無法再通過驗證。
  </Step>
</Steps>

也請在到期之前進行輪替:即將到期的金鑰會在金鑰清單中標示為即將到期。已到期的金鑰將無法通過驗證,使用該金鑰發出的請求會傳回 `401`,代碼為 [`credential_expired`](/zh-Hant/developers/v1/errors/credential_expired)。

## 立即撤銷

撤銷會立即生效且不可復原,沒有重疊期間,也無法還原。一旦懷疑金鑰的密鑰已外洩,請立即撤銷該金鑰;若只是要替換仍正常運作的憑證,則請改用輪替。

使用已撤銷金鑰發出的請求會傳回 `401`,代碼為 [`credential_revoked`](/zh-Hant/developers/v1/errors/credential_revoked)。若您需要一次停止某項整合所持有的所有金鑰,請改為停用其服務帳戶。


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