共有リンクのワンタイムパスコードイベント

ワンタイムパスコード (OTP) 保護では、公開共有リンク (accessがopenに設定されているリンク) の匿名受信者がコンテンツにアクセスするにあたり、受信トレイに送信されるコードを使用してメールアドレスの認証を受ける必要があります。OTPで保護されているリンクにどのユーザーがアクセスしたか、どのコードがどのユーザーに送られたか、OTP設定がどのように変更されたかを監査するには、ストリームの以下のイベントを使用します。

イベントタイプ	トリガーのタイミング
`ITEM_SHARED_UPDATE`	共有リンクの設定が更新された時点。OTPの変更内容は、`additional_details.sharedLinkSettings`に記録されています。
`SHARED_LINK_ONE_TIME_PASSCODE_ACCESS`	閲覧者がOTPで保護されている共有リンクを開き、Boxによりアクセスの許可、アクセスの拒否、パスコードの要求のいずれかの判定が下された時点。
`SHARED_LINK_ONE_TIME_PASSCODE_CHALLENGE`	受信者がパスコードを受け取るためにメールアドレスを送信したか、認証のためにパスコードを送信した時点。

ここに挙げたイベントはいずれも、標準的なオブジェクトスキーマに従っており、admin_logsとadmin_logs_streamingのどちらのストリームタイプでも利用できます。イベントを閲覧できるのは、企業の管理者であって、共有された項目の所有者でもあるユーザーのみです。

OTPイベントには、企業の外部のユーザーを含めた受信者のメールアドレスが含まれています。email、grantedEmail、およびアクセスリストのvalueフィールドは、個人を特定できる情報に該当します。そのため、これらは組織のデータ保護ポリシーに従って取り扱うようにしてください。

OTPモード

modeフィールドとotpModeフィールドで使用する値は、のone_time_passcode.modeフィールドと同じです。Boxウェブアプリでは、allowlistモードのラベルは [Only people added to the link’s Access List (リンクのアクセスリストに追加されているユーザーのみ)] になっています。

値	説明
`none`	OTP保護がオフになっています。リンクを知っていれば誰でも、パスコードなしでアクセスできます。
`open`	どの受信者も、パスコードをリクエストし、かつメールアドレスの認証を済ませれば、リンクにアクセスできます。
`allowlist`	受信者のうち、メールアドレスがリンクのアクセスリストのいずれかのエントリと一致しているユーザーのみが、リンクにアクセスできます。

OTP設定の更新

既存のITEM_SHARED_UPDATEイベントのadditional_details.sharedLinkSettingsには、oldVisibilityStatus、newIsPasswordProtectedなどの共有リンク設定のほか、それぞれの変更の前後のOTP構成が格納されています。このイベントは、OTPのオンとオフの切り替え、openモードとallowlistモードの切り替え、およびアクセスリストのエントリの追加または変更を記録するものです。このイベントは、Boxウェブアプリや、共有リンクエンドポイントを通じた変更 (など) によってトリガーされます。共有リンクの更新にOTPが関与しない場合には、OTPフィールドがnullになります。

フィールド	説明
`oldOneTimePasscodeSettings`	更新前のOTP設定。
`newOneTimePasscodeSettings`	更新後のOTP設定。
`oldOneTimePasscodeSettings.mode`, `newOneTimePasscodeSettings.mode`	OTPモード。`none`、`open`または`allowlist`のいずれかです。
`oldOneTimePasscodeSettings.allowlist`, `newOneTimePasscodeSettings.allowlist`	アクセスリストのエントリ。`mode`が`none`または`open`の場合には`null`になります。
`allowlist[].type`	単一のメールアドレスの場合には`email`、ドメインのメールアドレスすべての場合には`domain`。
`allowlist[].value`	メールアドレス、または`@`なしのドメイン。例: `example.com`。

以下は、所有者がリンクのアクセスリストから特定のドメインを削除した場合の例です。

{
  "source": {
    "item_type": "file",
    "item_id": "1234567890123",
    "item_name": "Q3 pricing proposal.pdf",
    "parent": {
      "type": "folder",
      "name": "Sales",
      "id": "998877665544"
    },
    "owned_by": {
      "type": "user",
      "id": "5544332211",
      "name": "Owner Name",
      "login": "owner@example.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "5544332211",
    "name": "Owner Name",
    "login": "owner@example.com"
  },
  "action_by": null,
  "created_at": "2026-09-14T09:15:22-07:00",
  "event_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c01",
  "event_type": "ITEM_SHARED_UPDATE",
  "ip_address": "198.51.100.7",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "shared_link_id": "l07r8kq89kna2qhjaaurkv4cey6boyjp",
    "sharedLinkSettings": {
      "oldVisibilityStatus": "Open",
      "newVisibilityStatus": "Open",
      "oldIsPasswordProtected": false,
      "newIsPasswordProtected": false,
      "oldCanPreview": true,
      "newCanPreview": true,
      "oldCanEdit": false,
      "newCanEdit": false,
      "oldCanDownload": true,
      "newCanDownload": true,
      "oldIsExpirationDateSet": false,
      "newIsExpirationDateSet": false,
      "oldOneTimePasscodeSettings": {
        "mode": "allowlist",
        "allowlist": [
          { "type": "email", "value": "alice@example.com" },
          { "type": "domain", "value": "partner.example.com" }
        ]
      },
      "newOneTimePasscodeSettings": {
        "mode": "allowlist",
        "allowlist": [
          { "type": "email", "value": "alice@example.com" }
        ]
      }
    }
  }
}

以下は、allowlistをopenモードに切り替えた所有者のadditional_detailsを示した例です。

{
  "additional_details": {
    "sharedLinkSettings": {
      "oldOneTimePasscodeSettings": {
        "mode": "allowlist",
        "allowlist": [
          { "type": "email", "value": "alice@example.com" },
          { "type": "domain", "value": "partner.example.com" }
        ]
      },
      "newOneTimePasscodeSettings": {
        "mode": "open",
        "allowlist": null
      }
    }
  }
}

OTPのアクセス判定

サインイン済みのBoxユーザーであるか、匿名の受信者であるかを問わず、誰かがOTPで保護されている共有リンクを開くと、その都度SHARED_LINK_ONE_TIME_PASSCODE_ACCESSイベントがトリガーされます。decisionフィールドとreasonフィールドでは、その結果を確認できます。このイベントでは、additional_detailsフィールド内のsharedLinkOneTimePasscodeAccessオブジェクトにアクセス判定が格納されます。このオブジェクトのフィールドは以下のとおりです。

フィールド	説明
`otpMode`	アクセスが評価された時点のOTPモード。`open`または`allowlist`のいずれかです。
`decision`	結果。`granted`、`denied`または`otp_required`のいずれかです。
`reason`	判定の理由。以下の表を参照してください。
`grantedEmail`	アクセスが許可されたメールアドレス。`decision`が`granted`の場合にのみ確認できます。これ以外の判定の場合には、閲覧者のIDが`created_by`に格納されます。

sharedLinkOneTimePasscodeAccessでは、値のないフィールドが省略されます。値がnullに設定されることはありません。

`decision`	`reason`	説明
`granted`	`owner_or_collab`	閲覧者が項目の所有者またはコラボレータです。
`granted`	`session_reuse`	匿名の受信者が、過去1時間の間にすでにメールアドレスの認証を済ませています。
`granted`	`auto_verified_allowlist`	サインイン済みのBoxユーザーのメールアドレスが、アクセスリストのエントリと一致しています。
`granted`	`exempt_open`	サインイン済みのBoxユーザーが、`open`モードのリンクを開きました。
`denied`	`allowlist_miss`	閲覧者のメールアドレスが、アクセスリストのエントリのいずれとも一致しません。
`denied`	`evaluation_failure`	Boxがアクセスを評価できませんでした。
`otp_required`	`otp_required`	閲覧者は、パスコードでメールアドレスの認証を受ける必要があります。

以下は、セッションで匿名の受信者がすでにメールアドレスの認証を済ませていた場合の例です。

{
  "source": {
    "item_type": "file",
    "item_id": "1234567890123",
    "item_name": "Q3 pricing proposal.pdf",
    "parent": {
      "type": "folder",
      "name": "Sales",
      "id": "998877665544"
    },
    "owned_by": {
      "type": "user",
      "id": "5544332211",
      "name": "Owner Name",
      "login": "owner@example.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "2",
    "name": "Unknown User",
    "login": ""
  },
  "action_by": null,
  "created_at": "2026-09-14T14:22:37-07:00",
  "event_id": "12345678-abcd-4321-8765-abcdef012345",
  "event_type": "SHARED_LINK_ONE_TIME_PASSCODE_ACCESS",
  "ip_address": "203.0.113.42",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "shared_link_id": "l07r8kq89kna2qhjaaurkv4cey6boyjp",
    "sharedLinkOneTimePasscodeAccess": {
      "otpMode": "allowlist",
      "decision": "granted",
      "reason": "session_reuse",
      "grantedEmail": "recipient@partner.example.com"
    }
  }
}

以下の例は、サインイン済みではあるものの、メールアドレスがアクセスリストにないユーザーのcreated_byとadditional_detailsを示したものです。

{
  "created_by": {
    "type": "user",
    "id": "88776655",
    "name": "Viewer Name",
    "login": "viewer@partner.example.com"
  },
  "event_type": "SHARED_LINK_ONE_TIME_PASSCODE_ACCESS",
  "additional_details": {
    "shared_link_id": "l07r8kq89kna2qhjaaurkv4cey6boyjp",
    "sharedLinkOneTimePasscodeAccess": {
      "otpMode": "allowlist",
      "decision": "denied",
      "reason": "allowlist_miss"
    }
  }
}

OTPチャレンジ

SHARED_LINK_ONE_TIME_PASSCODE_CHALLENGEイベントは、パスコードチャレンジの各段階でトリガーされます。具体的には、受信者がコードを受信するメールアドレスを送信した段階 (send段階) と、受信者がコードを送信した段階 (verify段階) の2段階があります。このイベントでは、チャレンジの詳細をイベントのadditional_detailsフィールドにあるsharedLinkOneTimePasscodeChallengeオブジェクトに格納します。このオブジェクトのフィールドは以下のとおりです。

フィールド	説明
`otpMode`	チャレンジが処理された時点のOTPモード。`open`または`allowlist`のいずれかです。
`phase`	チャレンジの段階。`send`または`verify`のいずれかです。
`result`	その段階の結果。以下の表を参照してください。
`email`	受信者が送信したメールアドレス。段階、結果を問わず必ず存在します。

`result`	説明
`ok`	`send`段階では、コードが送信されたことを示します。`verify`段階では、送信されたコードが正しく、メールアドレスが認証できたことを示します。
`invalid_code`	送信されたコードが正しくありません。
`expired_code`	送信されたコードの有効期限が切れています。
`allowlist_miss`	メールアドレスが、アクセスリストのエントリのいずれとも一致しません。
`rate_limited`	リクエストがパスコードのリクエストまたは認証の回数上限を超過しました。
`captcha_required`	受信者が先に進むには、CAPTCHAを完了する必要があります。
`service_unavailable`	Boxがリクエストを処理できませんでした。

以下は、受信者に送られるコードの一例です。

{
  "source": {
    "item_type": "file",
    "item_id": "1234567890123",
    "item_name": "Q3 pricing proposal.pdf",
    "parent": {
      "type": "folder",
      "name": "Sales",
      "id": "998877665544"
    },
    "owned_by": {
      "type": "user",
      "id": "5544332211",
      "name": "Owner Name",
      "login": "owner@example.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "2",
    "name": "Unknown User",
    "login": ""
  },
  "action_by": null,
  "created_at": "2026-09-14T14:22:07-07:00",
  "event_id": "9f1c3a8b-4e7d-4b21-9c19-2a2f5a6c1a01",
  "event_type": "SHARED_LINK_ONE_TIME_PASSCODE_CHALLENGE",
  "ip_address": "203.0.113.42",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "shared_link_id": "l07r8kq89kna2qhjaaurkv4cey6boyjp",
    "sharedLinkOneTimePasscodeChallenge": {
      "otpMode": "allowlist",
      "phase": "send",
      "result": "ok",
      "email": "alice@example.com"
    }
  }
}

以下の例は、同じ受信者が送信したコードが正しくなかった場合のadditional_detailsを示したものです。

{
  "additional_details": {
    "shared_link_id": "l07r8kq89kna2qhjaaurkv4cey6boyjp",
    "sharedLinkOneTimePasscodeChallenge": {
      "otpMode": "allowlist",
      "phase": "verify",
      "result": "invalid_code",
      "email": "alice@example.com"
    }
  }
}

プレビューイベントとダウンロードイベント

匿名の受信者がOTPで保護されているリンクを通じてコンテンツをプレビューまたはダウンロードした場合、その受信者はPREVIEWイベントとDOWNLOADイベントでcreated_by.idが2である匿名ユーザーとして識別されます。この2つのイベントには、認証済みのメールアドレスは含まれません。どのメールアドレスのユーザーがリンクにアクセスしたかを確認する場合には、SHARED_LINK_ONE_TIME_PASSCODE_ACCESSイベントとSHARED_LINK_ONE_TIME_PASSCODE_CHALLENGEイベントを使用します。

はじめに

アプリケーションと統合

IDとアクセス

APIの利用

トラブルシューティング

コンテンツ

コラボレーション

メタデータと検索

イベントとWebhook

ユーザー

インテリジェントなワークフロー

電子サイン

セキュリティとコンプライアンス

共有リンクのワンタイムパスコードイベント

OTPモード

OTP設定の更新

OTPのアクセス判定

OTPチャレンジ

プレビューイベントとダウンロードイベント

​OTPモード

​OTP設定の更新

​OTPのアクセス判定

​OTPチャレンジ

​プレビューイベントとダウンロードイベント

OTPモード

OTP設定の更新

OTPのアクセス判定

OTPチャレンジ

プレビューイベントとダウンロードイベント