Dvina MCP

使用 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 連線。

檢查、輪替或撤銷權杖

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

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

建立、輪替和撤銷權杖的操作都會記錄在稽核記錄中。

新增 webhook

Webhook 會將 Livespace 的事件傳送到你指定的網址，這些事件與稽核記錄中的記錄相同。

  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，請選擇刪除…，然後選擇刪除以確認。之後便不會再向它傳送任何內容。