ブラウザフィンガープリントAPI

EchoScanのブラウザフィンガープリントAPIは、重要な操作を実行する前に、デバイスの継続性とアクセスリスクを確認したいオンラインサービス向けの連携機能です。Browser Verifierが現在のブラウザ環境を観測し、サーバー発行の{ imprint }を返します。導入先のバックエンドは、Secret API Keyを使ってLiteまたはProのReportを照会します。登録、ログイン、トライアル付与、APIキー作成、決済などの最終判断をサーバー側に保ち、Reportを読むための認証情報をブラウザへ公開しません。

連携の流れ

1. ConsoleでBrowser Environmentを作成し、利用を許可するOriginを正確に設定します。
2. 導入先が管理するページにBrowser Verifierを追加し、公開可能なEnvironment IDを設定します。
3. 保護対象の操作でrun()を呼び、ブラウザからの送信が完了した後に{ imprint }を受け取ります。
4. Imprintを、登録、ログイン、利用枠、取引などの実際のリクエストと一緒に導入先のバックエンドへ送ります。
5. サーバー側でSecret API Keyを使い、GET /api/v1/fingerprint/report/{imprint}を照会します。
6. risk.statusと利用可能なReport項目を、アカウント、決済、利用条件、追加認証の情報と組み合わせます。

許可、追加認証、確認、拒否の最終判断は導入先のバックエンドが行います。EchoScanは、導入先固有のrecommended_actionを返しません。

Browser VerifierがImprintだけを返す理由

Imprintは、サーバーが発行するReportの識別子です。完全なデバイスReportでも、繰り返し使える秘密情報でもありません。ブラウザはこの短い値を既存の業務リクエストに添えるだけで済むため、保護されたReportの照会をバックエンド側に限定できます。

完全なReportには、デバイス、ブラウザ、OS、ネットワーク、継続性、最近のアクティビティに関する情報が含まれる場合があります。誤検知による影響や操作の重要度を考慮できるよう、導入先が持つ他のサーバー側情報と合わせて扱います。

Environment IDとSecret API Keyの境界

Environment IDはenv_<32 lowercase hex>形式の、公開可能なブラウザ導入識別子です。EchoScanはリクエスト元のOriginを、Browser Environmentに登録されたAllowed Originsと完全一致で照合します。Environment IDには、Reportの読み取り、Historyの照会、Workspaceの管理を行う権限はありません。

Secret API KeyはReportとHistoryのリクエストを認証します。サーバー実行環境またはシークレット管理基盤だけに保存し、ブラウザbundle、公開環境変数、HTML、localStorage、ログ、クライアントリクエストには含めないでください。

Browser EnvironmentとSecret API Keyは別々のリソースです。KeyをローテーションしてもEnvironment IDは変わらず、Environmentを無効にしてもKeyは失効しません。

LiteとProのReport

LiteとProは同じReport API v1エンドポイントを使い、認証に使用したKeyのプランによってレスポンスの情報量が決まります。

• LiteはDevice ID、seen_before、access_count、全体のrisk.status、ブラウザ、OS、基本的なネットワーク情報を返します。
• Proは、製品運用向けのリスク理由、初回・前回の観測時刻、詳しいネットワーク情報、最近のアクティビティ、Historyを追加します。
• 公開されるリスク状態はPASS、SUSPICIOUS、DECEPTIVEです。

まずは業務ポリシーに必要な情報を基準に選びます。PASS以外のアクセスに追加認証を求めるだけならLiteから始められます。判断理由の説明や調査が必要な運用では、Proの追加情報が役立ちます。

シグナルの分類と利用場面

EchoScanは、ブラウザ、デバイス、描画、ネットワーク、自動化に関するシグナルを評価します。Reportには運用で扱いやすい結果を示しますが、内部のDetector名、重み、しきい値、回避条件は公開しません。

登録、ログイン、無料トライアルやクレジットの付与、APIキー作成、パスワード再設定、決済、クーポン、投票、フォーム送信など、最終判断をバックエンドで行う操作に利用できます。操作ごとに損失と誤検知の影響が異なるため、同じポリシーを一律に適用するものではありません。

Node.js、Go、Python、Rustからの利用

サーバーHTTP APIが基本の連携方法です。認証付きのHTTPSリクエストを送れるバックエンドであれば利用できます。Node.js、Go、Python、Rust向けのSDKも、同じReportの照会経路を扱います。ブラウザ側の収集は@echoscan/browser-verifierが担当します。

現在のパッケージ名、インストール方法、リクエスト例、レスポンス項目、エラー処理は開発者ドキュメントで確認してください。説明用に示した導入先所有のパスを、EchoScanの正式なエンドポイントとして扱わないでください。

APIが証明しないこと

ブラウザフィンガープリントは、法的な本人確認、生体認証、特定の人物がデバイスを操作したことの証明にはなりません。共有端末、仮想環境、プライバシー機能、ソフトウェア更新、ハードウェア変更、ネットワーク変更によって観測結果は変化します。再訪デバイスが常に信頼できる人物によるものとは限らず、変化したデバイスが攻撃者によるものとも限りません。

EchoScanは、不正行為や意図も証明しません。アカウント履歴、決済、利用条件、追加認証、アクセス頻度、誤検知による影響と組み合わせて判断してください。

次のステップ

開発者ドキュメントを開き、Browser VerifierとReport API v1を連携してください。導入前にファーストパーティ画面の表示内容を確認する場合は、公開ブラウザフィンガープリントScanを実行できます。

ブラウザフィンガープリントAPIのよくある質問

ブラウザ側のコードには何が返りますか？

Browser Verifierが返すのは、サーバー発行の{ imprint }だけです。導入先はその値をバックエンドへ送り、Secret API Keyを使ってReport API v1を照会します。

Environment IDでデバイスのReportを読めますか？

読み取れません。Environment IDは公開可能なブラウザ導入識別子で、リクエスト元をAllowed Originsと照合するために使われます。ReportやHistoryへアクセスする認証権限はありません。

フィンガープリントだけで個人を確実に特定できますか？

できません。EchoScanが提供するのはデバイスの継続性とアクセスリスクの判断材料です。法的な本人確認、意図、不正行為を証明するものではなく、最終判断は導入先が行います。