設定 › APIアクセスでパーソナルアクセストークンを作成すると、スクリプトやMCPクライアントがあなたとしてDvinaを使えるようになります。管理者はここでWebhookを追加して、Livespaceのイベントを自分のシステムに送信することもできます。
APIアクセスはEnterpriseプランで利用できます。すべてのメンバーが自分のトークンを作成できます。Webhookが表示されるのは、オーナーと管理者だけです。
トークンを作成する
- 設定を開き、APIアクセスを選択します。
- パーソナルアクセストークンで、トークンを作成を選択します。
- 後で用途がわかるように、名前を入力します。
- アクセス権で、読み取り専用または読み取りと書き込みを選択します。
- 有効期限で、30日後、90日後、365日後、無期限のいずれかを選択します。
- トークンを作成を選択します。
- トークンをコピーでトークンをコピーし、安全な場所に保管します。トークンが表示されるのはこのときだけです。
トークンは、作成したLivespaceで、あなたの現在のロールに従って、あなたとして動作します。読み取り専用のトークンは読み取りができますが、追加や変更はできません。
MCPクライアントでトークンを使うには、OAuthの代わりにAPIキーで接続するを参照してください。
トークンを確認・ローテーション・取り消す
パーソナルアクセストークンには、あなたのトークンがアクセス権とともに一覧表示されます。トークンを選択すると、先頭の文字列、アクセス権、最終使用日時、有効期限を確認できます。
- トークンを置き換えるには、ローテーション…を選択し、確認のためにローテーションを選択します。新しいトークンに置き換わり、古いトークンはすぐに使えなくなります。トークンをコピーで新しいトークンをコピーします。
- トークンを無効にするには、取り消す…を選択し、確認のために取り消すを選択します。そのトークンを使っているものは、すぐに動作しなくなります。
トークンの作成、ローテーション、取り消しは、監査ログに記録されます。
Webhookを追加する
Webhookは、監査ログと同じ記録であるLivespaceのイベントを、指定したアドレスに送信します。
- 設定 › APIアクセスのWebhookで、Webhookを追加を選択します。
- 名前とURLを入力します。公開HTTPS URLを使ってください。
- イベントは、すべてのイベントを受け取る場合は空欄のままにします。特定のアクションや領域を指定する場合は、
member.addedやsharing.*などを列挙します。 - 追加を選択します。
- 署名シークレットをコピーで、シークレットをコピーします。シークレットが表示されるのはこのときだけです。
DvinaにDvinaからこのアドレスにアクセスできませんと表示された場合は、公開HTTPS URLを使ってください。
各リクエストの署名を確認する
DvinaはイベントをJSON形式のバッチで送信し、すべてのリクエストに署名します。署名シークレットを使って、リクエストがDvinaから送信されたことを確認してください。
- 各リクエストには、
t=<timestamp>,v1=<signature>のようなX-Dvina-Signatureヘッダーが含まれます。 - 署名は、タイムスタンプ、ピリオド、リクエスト本文を連結したものから、署名シークレットを使って生成したHMAC-SHA256を16進数で表したものです。
- 自分で署名を計算して比較してください。署名が一致しないリクエストや、タイムスタンプが古すぎるリクエストは拒否してください。
Webhookを確認・変更する
Webhookには、各Webhookとそのステータス（オン、一時停止中、失敗中）が表示されます。詳細を確認するには、Webhookを選択します。
- 変更するには、名前、URL、またはイベントを編集して、保存を選択します。
- 一時停止するには、イベントを送信をオフにします。送信を再開するには、もう一度オンにします。
- 動作状況を確認するには、ステータスと送信済みのイベント数を確認します。送信に失敗しているWebhookには、最後のエラーが表示されます。Dvinaは再試行を続け、失敗を監査ログに記録します。
- シークレットを変更するには、**新しい署名シークレット…**を選択して、確認します。リクエストはすぐに新しいシークレットで署名されるため、受信側も直ちに更新してください。
- 削除するには、削除…を選択し、確認のために削除を選択します。そのWebhookへの送信は停止します。