Watch-IP

ログイン位置情報を直前の保存済み位置情報と比較する

短時間でのIP由来の位置情報の大きな変化は、確認が必要な場合があります。POST /v1/risk/checkは、ユーザーの現在の推定位置情報を直前の保存済み地点と比較し、距離、経過時間、想定される速度、リスク分類を返します—独立したリスクプランの適用とチェックアウトの提供状況は未確認のため、統合前に利用可否についてお問い合わせください。

リスクチェックへのアクセスについて相談するリスクチェックのリファレンスを読む →

利用可否

このエンドポイントは、キーがシークレットキーであることを確認するIPルックアップと同じミドルウェアを共有しています—独立したリスクプランファミリーを強制するものではなく、シードされたリスク料金には有効な価格設定がありません。本番環境でこれに依存する前に、現在の条件と利用可否についてお問い合わせください。

入力とシークレットキーの利用

userId、ip、そして任意のcommitブール値(デフォルトはtrue)を含むJSON本文を、Authorization: Bearer YOUR_SECRET_KEYを使ったシークレットキーでPOST /v1/risk/checkに送信してください—サーバー間通信専用で、ブラウザから呼び出すことは絶対にありません。

最初の観測

ユーザーの最初のチェックには比較対象となる直前の位置情報がありません:risk: "low"、impossibleTravel: false、null のdistance/speed/elapsed値、そしてnullのpreviousLocationを返します。そして—commitがfalseでなければ—この観測結果を新しいベースラインとして保存します。

以降の観測

以降のチェックでは、直前の地点と現在の地点との大圏距離を経過時間と比較し、想定される速度を算出します。500km/h未満は「low」、500〜900km/hは「medium」(実際の長距離フライトはこの境界付近に着陸することがあります)、900km/hを超えると「high」となり、impossibleTravel: trueが返されます。

commitフラグ

commitのデフォルトはtrueです。例えばステップアップ認証の判断の前段など、投機的な事前チェックの場合はfalseに設定してください。これにより、保存済みのベースラインを読み取るだけで、更新しません。これにより、正当なチェックがユーザーの実際の位置情報履歴を損なうことがありません。

位置情報が見つからない場合

ipが緯度・経度に解決できない場合、このエンドポイントは信頼度の低い推測ではなく422を返します。

保持と削除

v1は(お客様のアカウント、userId)のペアごとに、最新のコミット済みの観測結果を1件のみ保存します。自動的な期限切れはなく、現在削除用のエンドポイントもないため、次にコミットされたチェックによって上書きされるまで保持されます。これは、単一のリクエスト/レスポンスのサイクルを超えてuserIdに紐付いた位置情報を保存するため、このエンドポイントを使用することで、Watch-IPはお客様に代わってそのデータを処理する処理者(processor)となります—データ処理契約(DPA)をご覧ください。

誤検知

v1にはVPNやデータセンターを考慮した抑制機能がないため、VPNの高速な切り替えや通常のモバイルネットワークのIPの入れ替わりによって、結果が高く判定されることがあります。すべての分類結果は、自社の審査プロセスに向けた生のシグナルとして扱い、最終的な判定として扱わないでください。

レスポンスフィールド

risk
上記の想定速度のしきい値による、low、medium、またはhigh。
impossibleTravel
risk: "high"を示すブール値の略記。
distanceKm, impliedSpeedKmh, elapsedSeconds
直前の観測と現在の観測の間の距離と時間、およびそこから算出される速度。ユーザーの最初のチェックではnull。
previousLocation
この呼び出しの前に保存されていたベースラインのcountry、latitude、longitude、observedAt。ユーザーの最初のチェックではnull。
currentLocation
この呼び出しで指定されたipから解決されたcountry、latitude、longitude。

事前チェックしてからコミットする

バックエンドcURL

# 自社の認証判断前の投機的チェック—ベースラインは更新されません。
curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1", "commit": false}'

# 自社のパスワード/2FA検証が成功した後、新しいベースラインをコミットします。
curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

commitのデフォルトはtrueのため、上記の2回目の呼び出しは保存済みのベースラインを更新します。commit: falseを指定した最初の呼び出しは更新しません。

よくある質問

最初のチェックでは何が起こりますか?

常にrisk: "low"とnullのpreviousLocationを返します—まだ現在の位置情報と比較する対象がないためです。

VPNの切り替えを抑制しますか?

いいえ。v1にはVPNやデータセンターを考慮した抑制機能がないため、ログイン間でネットワークやVPN出口を切り替えるだけでmediumまたはhighの結果になる可能性があります。

high判定は侵害の証明ですか?

いいえ。これは生の距離÷時間の計算です。単独の判定として扱うのではなく、自社の認証に関する根拠と組み合わせてください。

ベースラインの更新を避けられますか?

はい—commit: falseを指定してください。チェック自体は実行されて結果が返されますが、保存済みの位置情報は置き換えられません。

直前の位置情報はどのくらい保持されますか?

そのuserIdに対する次のコミット済みチェックによって上書きされるまで、無期限に保持されます—現在の実装には自動的な期限切れも削除用のエンドポイントもありません。

関連ページ