> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 公開共有リンクのワンタイムパスコード (OTP) の設定変更、アクセス判定、パスコードチャレンジをEnterprise Eventを使って監査します。

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

| イベントタイプ | トリガーのタイミング |
| - | - |
| `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`のどちらのストリームタイプでも利用できます。イベントを閲覧できるのは、企業の管理者であって、共有された項目の所有者でもあるユーザーのみです。

> [!WARNING]
>
> 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`。 |

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

```json theme={null}
{
  "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`を示した例です。

```json theme={null}
{
  "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` | 閲覧者は、パスコードでメールアドレスの認証を受ける必要があります。 |

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

```json theme={null}
{
  "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`を示したものです。

```json theme={null}
{
  "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がリクエストを処理できませんでした。 |

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

```json theme={null}
{
  "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`を示したものです。

```json theme={null}
{
  "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`イベントを使用します。

**関連するAPI**

**関連するガイド**