用途限定トークンと失効

トークン本体に実データを入れない

外部には推測困難な不透明トークンを渡し、用途や期限はサーバー側で管理する設計例です。漏洩時の被害を抑えるため、トークンだけで処理を許可せず、利用先の認証情報も照合します。

token_hash

受け取ったトークンの照合値。生のトークンをログや通常の管理画面に残さない。

audience

トークンを利用できる相手。別の連携先への持ち回りを拒否する。

scope / purpose

取得できる情報と業務上の用途。広い権限を初期値にしない。

resource_ref

対象の注文や配送先。別レコードの参照に流用できないようにする。

expires_at / remaining_uses

有効期限と利用回数。期限切れと消費済みをサーバー側で拒否する。

単回利用と応答紛失

代理IDは保管した住所の参照先です。配送トークンは、特定の注文について指定アプリが許可された項目を取得するための追加条件です。両方とも機密として扱います。単回トークンは成功した取得で消費され、同じ応答の再取得は保証しません。通信結果が不明なら注文・処理状況を確認してから再発行を判断します。

期限切れ・取り消し・情報変更

住所の上書き編集はせず、新しい住所を登録します。現在の注文対応を照会し、そのVersionをexpectedVersionにして注文を変更し、新しい版のトークンを発行します。注文版が変わると旧版の全トークンは使えません。同じ版での追加発行だけでは旧トークンは失効しません。旧住所を使う別注文と保持条件を業務側で確認し、不要な旧住所だけを削除します。変更前に取得済みの平文は回収できません。

状態遷移

active → consumed / expired / revoked。失効済みの状態を再有効化しない。

キャッシュ

失効反映の遅れを抑える。高リスク処理は権威ある状態を確認する。

限界

失効によって連携先がすでに取得した実データまで回収できるわけではない。

DATA / INTEGRATION EXAMPLE

データ・連携の具体例

以下は設計を説明するためのサンプルです。フィールド名・値は例示で、実行用のAPIリファレンスではありません。

{
  "operation": "配送先参照トークンの発行の設計例",
  "request": {
    "proxy_id": "nym_example_01",
    "resource_ref": "order_example_01",
    "audience": "carrier-a",
    "scope": [
      "shipping.address.read"
    ],
    "expires_in_seconds": 600,
    "max_uses": 1
  },
  "response": {
    "token": "tok_example_not_a_real_token",
    "expires_in_seconds": 600
  }
}

600秒・1回は説明用の値です。署名付きJWTを採用する場合も、署名だけでは期限前の失効や一回限りの利用を保証できず、別途状態管理が必要です。

関連する技術設計

業務とシステムに合わせた連携設計。

保有する情報、連携先、必要な処理を整理し、情報の露出を減らす方法を検討します。