# 使用 API 存取

> 為指令碼和 MCP 用戶端建立個人存取權杖，並透過 webhook 將 Livespace 的事件傳送到你自己的系統。

在「設定」› **API 存取**中，你可以建立個人存取權杖，讓指令碼或 MCP 用戶端以你的身分使用 Dvina。管理員也可以在這裡新增 webhook，將 Livespace 的事件傳送到自己的系統。

Enterprise 方案包含 API 存取功能。每位成員都可以建立自己的權杖；只有擁有者和管理員能看到 **Webhook**。

## 建立權杖

1. 開啟「設定」，選擇 **API 存取**。
2. 在**個人存取權杖**下，選擇**建立權杖**。
3. 輸入**名稱**，方便日後辨識哪些程式或服務使用這個權杖。
4. 選擇**存取權限**：**唯讀**或**讀取與寫入**。
5. 選擇**到期時間**：**30 天後**、**90 天後**、**365 天後**或**永不到期**。
6. 選擇**建立權杖**。
7. 在**複製你的權杖**下，複製權杖並妥善保存。權杖只會在此時顯示一次。

權杖會在你建立它的 Livespace 中，以你的身分和你目前在該 Livespace 中的角色運作。**唯讀**權杖可以讀取內容，但無法新增或變更任何內容。

若要在 MCP 用戶端中使用權杖，請參閱[使用 API 金鑰而非 OAuth 連線](/docs/dvina-mcp/overview#connect-with-an-api-key-instead-of-oauth)。

## 檢查、輪替或撤銷權杖

你的權杖會列在**個人存取權杖**下，並顯示各自的存取權限。選擇一個權杖，即可查看它的**開頭字元**、**存取權限**、**上次使用時間**和**到期時間**。

- **若要替換權杖**，選擇**輪替…**，再選擇**輪替**以確認。新權杖會取代舊權杖，舊權杖會立即失效。在**複製你的權杖**下複製新權杖。
- **若要停用權杖**，選擇**撤銷…**，再選擇**撤銷**以確認。所有使用該權杖的程式或服務都會立即停止運作。

建立、輪替和撤銷權杖的操作都會記錄在[稽核記錄](/docs/teams/audit-log)中。

## 新增 webhook

Webhook 會將 Livespace 的事件傳送到你指定的網址，這些事件與[稽核記錄](/docs/teams/audit-log)中的記錄相同。

1. 在「設定」› **API 存取**中的 **Webhook** 下，選擇**新增 Webhook**。
2. 輸入**名稱**和 **URL**。請使用可公開存取的 HTTPS URL。
3. 在**事件**下，留空即可接收所有事件，或列出操作和範圍，例如 `member.added` 或 `sharing.*`。
4. 選擇**新增**。
5. 在**複製簽章密鑰**下，複製密鑰。密鑰只會在此時顯示一次。

如果 Dvina 顯示 **Dvina 無法連線至此網址**，請使用可公開存取的 HTTPS URL。

### 驗證每個請求的簽章

Dvina 會以 JSON 格式分批傳送事件，並為每個請求加上簽章。使用簽章密鑰驗證請求是否來自 Dvina：

- 每個請求都有一個 `X-Dvina-Signature` 標頭，格式如 `t=<timestamp>,v1=<signature>`。
- 簽章是以你的簽章密鑰，對時間戳記、句點和請求本文依序串接後的內容計算出的 HMAC-SHA256，並以十六進位表示。
- 自行計算簽章並進行比對。如果請求的簽章不符，或時間戳記過舊，請拒絕該請求。

## 查看或變更 webhook

你的 webhook 會列在 **Webhook** 下，並顯示各自的狀態：**已啟用**、**已暫停**或**失敗中**。選取其中一個即可查看詳細資訊。

- **若要變更 webhook**，請編輯其**名稱**、**URL** 或**事件**，然後選擇**儲存**。
- **若要暫停 webhook**，請關閉**傳送事件**。再次開啟即可恢復傳送。
- **若要查看運作情況**，請查看其**狀態**和**已傳送**的事件數量。失敗中的 webhook 會顯示其**上次錯誤**。Dvina 會持續重試，並將失敗記錄在稽核記錄中。
- **若要變更其密鑰**，請選擇**新增簽署密鑰…**，然後確認。請求會立即改用新密鑰簽署，因此請立即更新接收端。
- **若要移除 webhook**，請選擇**刪除…**，然後選擇**刪除**以確認。之後便不會再向它傳送任何內容。

## 相關內容

- [透過 MCP 從其他 App 使用 Dvina](/docs/dvina-mcp/overview)
- [使用稽核記錄](/docs/teams/audit-log)
- [團隊概覽](/docs/teams/overview)