EchoScan API・導入ガイド

EchoScan は、ログイン、登録、決済などの重要な業務アクションに対して、デバイス ID とアクセスリスクを提供します。設定後はブラウザーが imprint を生成し、サーバーが Secret API Key を使って正式な Report を照会します。

自動評価 Agent を構築する場合は、Agent API ディスカバリーガイドで商品カタログ、OpenAPI 仕様、Agent Trial フローを確認してください。人間の Workspace ユーザーは、Secret API Key を共有せず OAuth 2.1 で本番 MCP Serverに接続できます。

推奨フロー

上から順に完了できる接続チェックリストです。最初の接続では、Console にウェブサイト URL を 1 件入力します。EchoScan が Web App と既定のサーバー API Key をまとめて作成します。ステップを選択またはスクロールすると、右側に実行境界、確認ポイント、想定される結果が補足表示されます。

Console の最初のウェブサイト設定を開き、Browser Verifier を実行するウェブサイトを入力します。例は https://shop.example.com です。Console が Path とクエリを正確な Origin に変換し、Web App と既定のサーバー API Key を 1 つのトランザクションで作成します。作成後、公開可能な env_... Environment ID をコピーします。

2. サーバー用 API Key を保存

最初のウェブサイト設定が成功すると、Console に既定の API Key の Secret が一度だけ表示されます。すぐにバックエンドの Secret Manager または環境変数へ保存し、ブラウザーコード、ログ、バージョン管理には含めません。その後は API Key 管理で Key を個別に作成、ローテーション、取り消しできます。Web App は変更されません。

3. Browser Verifier をウェブページに導入

Browser SDK をインストールし、手順 1 の Environment ID を createEchoScan({ environmentId }) に設定します。Allowed Origins は Console で管理するため、ブラウザーコードには公開 Environment ID だけを設定します。

4. Imprint を生成して送信

ログイン、登録、決済などの保護対象アクションで run() を呼び出します。返された imprint を業務リクエストと一緒に自社サーバーへ送信します。

5. バックエンドで Report を照会

手順 2 で保存した Secret API Key を使い、imprint で共通 Report Endpoint を照会します。正式なデバイス ID とリスク結果はサーバーの Report から取得します。

6. 業務判断を適用

risk.status を確認し、Pro では risk.reasons も確認します。アカウント、取引、業務コンテキストと組み合わせて、許可、追加確認、手動審査、拒否を決定します。ブラウザーには業務に必要な最小限の結果だけを返します。

ブラウザコードとサーバールートは同じリポジトリに置けます。境界は実行場所です。environmentId は公開可能ですが、API key はサーバー専用です。

ブラウザで imprint を生成

Direct mode では env_<32 lowercase hex> 形式の environmentId が必須です。Browser Verifier はフィンガープリントの Submit のときだけ使用し、Workspace ID を受け付けません。API key や Authorization もブラウザへ置きません。

インストール

npm install @echoscan/browser-verifier

JavaScript

import { createEchoScan } from '@echoscan/browser-verifier'

const sdk = createEchoScan({
  environmentId: 'env_0123456789abcdef0123456789abcdef'
})
const { imprint } = await sdk.run()

HTML

<script type="module">
  import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js'

  const sdk = createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  const { imprint } = await sdk.run()
</script>

<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
  const sdk = window.EchoScan.createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  sdk.run().then(({ imprint }) => {
    console.log(imprint)
  })
</script>

run() は { imprint } だけを返します。新しい Imprint は imp_<32 lowercase hex> 形式です。

Allowed Origins はブラウザ配備と設定ミスを保護します。秘密認証としては扱いません。https://staging.example.com:8443 や http://localhost:3000 のような完全な http / https Origin だけを登録します。scheme と port は保持し、host は小文字化して完全一致します。Path、Query、Fragment、UserInfo、ワイルドカード（*.example.com を含む）、裸のドメイン、null、file://、拡張機能 Origin は拒否されます。空の Allowlist または Origin Header の欠落では、すべての Public Submit を拒否します。

Browser Verifier パラメータ

パラメータ	意味
`environmentId`	公開可能な Browser Environment ID。サーバーが信頼済み Workspace を解決し、Allowed Origins を検証します
`imprint`	`run()` 成功時に返るサーバー発行の Report ID。保護対象の業務アクションと一緒にサーバーへ送ります

サーバーへ送信

業務 API に合う方法で、保護対象のアクションと一緒に Imprint を送ります。

リクエスト例

await fetch('/api/your-action', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...yourActionPayload,
    echoscanImprint: imprint
  })
})

リクエスト例

await fetch('/api/your-action', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-EchoScan-Imprint': imprint
  },
  body: JSON.stringify(yourActionPayload)
})

リクエスト例

await fetch('/api/echoscan/report', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ imprint })
})

上記の /api/echoscan/report は導入側が実装するサンプルパスで、EchoScan Endpoint ではありません。

Lite 導入

Lite は共通 Report Endpoint を使います。Secret key はサーバー実行コードだけが読み取ります。

report 照会

リクエスト例

GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <your_lite_key>
Accept: application/json

Node.js、Go、Python、Rust SDK は同じサーバー HTTP API のラッパーです。

バックエンド言語

SDK インストール / 依存

npm install @echoscan/echoscan

サーバー照会例

import { createLiteClient } from '@echoscan/echoscan'

const echoscan = createLiteClient({
  apiKey: process.env.ECHOSCAN_LITE_KEY
})

const report = await echoscan.getReport(imprint)
console.log(report.risk.status)

SDK インストール / 依存

go get github.com/echoscan/echoscan-go@latest

サーバー照会例

package main

import (
	"context"
	"log"
	"os"

	echoscan "github.com/echoscan/echoscan-go"
)

func main() {
	imprint := "imp_0123456789abcdef0123456789abcdef"
	echoscanClient, err := echoscan.NewLiteClient(os.Getenv("ECHOSCAN_LITE_KEY"))
	if err != nil {
		log.Fatal(err)
	}
	report, err := echoscanClient.GetReport(context.Background(), imprint)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("risk_status=%v", report["risk"].(map[string]any)["status"])
}

SDK インストール / 依存

pip install echoscan

サーバー照会例

import os
from echoscan import EchoScanLiteClient

imprint = "imp_0123456789abcdef0123456789abcdef"
echoscan_client = EchoScanLiteClient(os.environ["ECHOSCAN_LITE_KEY"])
report = echoscan_client.get_report(imprint)
print(report["risk"]["status"])

SDK インストール / 依存

[dependencies]
echoscan = "0.2.1"

サーバー照会例

use std::env;
use echoscan::LiteClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let imprint = "imp_0123456789abcdef0123456789abcdef";
    let api_key = env::var("ECHOSCAN_LITE_KEY")?;
    let echoscan = LiteClient::new(&api_key)?;
    let report = echoscan.get_report(imprint).await?;
    println!("{}", report["risk"]["status"]);
    Ok(())
}

Lite report

Lite は最小限の公開デバイス ID とリスク契約を返します。製品 Reason、Recent Activity、デバイス時刻、Pro ネットワーク詳細は含みません。

通常アクセスの例：

戻り値例

{
  "schema_version": "1.0",
  "imprint": "imp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-28T01:30:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": false,
    "access_count": 1
  },
  "risk": {
    "status": "PASS"
  },
  "browser": {
    "status": "PASS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "203.0.113.10",
    "country_code": "JP"
  }
}

疑わしいアクセスの例：

戻り値例

{
  "schema_version": "1.0",
  "imprint": "imp_11111111111111111111111111111111",
  "created_at": "2026-07-28T01:35:00Z",
  "device": {
    "id": "did_C98D76E54F32",
    "seen_before": false,
    "access_count": 1
  },
  "risk": {
    "status": "SUSPICIOUS"
  },
  "browser": {
    "status": "SUSPICIOUS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "198.51.100.20",
    "country_code": "US"
  }
}

再訪デバイスの例：

戻り値例

{
  "schema_version": "1.0",
  "imprint": "imp_22222222222222222222222222222222",
  "created_at": "2026-07-28T02:00:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": true,
    "access_count": 8
  },
  "risk": {
    "status": "PASS"
  },
  "browser": {
    "status": "PASS",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "PASS",
    "observed_ip": "203.0.113.10",
    "country_code": "JP"
  }
}

フィールド説明

フィールド	返却条件	意味
`schema_version`	常に返却します。	この Report が使用する公開データ構造のバージョンです。
`imprint`	常に返却します。	この検査 Report を一意に識別する番号です。
`created_at`	UTC で常に返却します。	この Report の生成時刻です。
`device`	常に返却します。	現在の Workspace におけるデバイスの識別結果と過去のアクセス状況です。
`device.id`	常に返却します。	現在の Workspace 内で使用するデバイス ID です。
`device.seen_before`	常に返却します。	今回のアクセス前にこのデバイスを確認済みかを示します。
`device.access_count`	今回のアクセスを含めて常に返却します。	現在の Workspace における、このデバイスの累計アクセス回数です。
`risk`	常に返却します。	今回のアクセスに対する総合リスク結果です。
`risk.status`	常に返却します。	今回のアクセスに対する総合リスクレベルです。
`browser`	常に返却します。	EchoScan が識別したブラウザー情報とリスク状態です。
`browser.status`	常に返却します。	今回のアクセスにおけるブラウザー識別情報のリスクレベルです。
`browser.name`	結果がある場合に返却します。	EchoScan が識別したブラウザー名です。
`browser.version`	結果がある場合に返却します。	EchoScan が識別したブラウザーのバージョンです。
`operating_system`	常に返却します。	EchoScan が識別した OS 情報とリスク状態です。
`operating_system.status`	常に返却します。	今回のアクセスにおける OS 環境のリスクレベルです。
`operating_system.name`	結果がある場合に返却します。	EchoScan が識別した OS 名です。
`operating_system.version`	結果がある場合に返却します。	EchoScan が識別した OS バージョンです。
`network`	常に返却します。	今回のアクセスに関するネットワーク情報とリスク状態です。
`network.status`	常に返却します。	今回のアクセスにおけるネットワークのリスクレベルです。
`network.observed_ip`	結果がある場合に返却します。	リクエストが EchoScan に到達したときの送信元グローバル IP アドレスです。
`network.country_code`	結果がある場合に返却します。	リクエスト送信元のグローバル IP に対応する国または地域コードです。

有限値の説明

フィールド	値	タイトル	意味	導入側の対応例
`device.seen_before`	`true`	確認済みのデバイス	今回のアクセス前に、このデバイスを確認済みです。
`device.seen_before`	`false`	初回の記録	今回のアクセスが、このデバイスの初回記録です。
`risk.status`	`PASS`	現在、注意が必要なリスクはありません	通常の業務ルールに沿って今回のアクセスを処理できます。	既存の業務フローを継続します。
`risk.status`	`SUSPICIOUS`	注意が必要なリスクがあります	アカウント情報や業務状況と合わせた追加判断に適した結果です。	追加認証、レート制限、または目視確認を行います。
`risk.status`	`DECEPTIVE`	明確な高リスクの兆候があります	偽装、自動化、または高リスクネットワークの明確な兆候があります。	より厳格な認証、制限、または目視確認を行います。
`browser.status`	`PASS`	ブラウザー情報は正常です	ブラウザー情報に注意が必要な異常はありません。
`browser.status`	`SUSPICIOUS`	ブラウザー情報に注意が必要です	ブラウザー情報に注意が必要な異常があります。
`browser.status`	`DECEPTIVE`	ブラウザー情報は高リスクです	ブラウザー情報に明確な偽装の兆候があります。
`operating_system.status`	`PASS`	OS 情報は正常です	OS 情報に注意が必要な異常はありません。
`operating_system.status`	`SUSPICIOUS`	OS 情報に注意が必要です	OS 情報に注意が必要な異常があります。
`operating_system.status`	`DECEPTIVE`	OS 情報は高リスクです	OS 情報に明確な偽装の兆候があります。
`network.status`	`PASS`	ネットワーク情報は正常です	ネットワーク情報に注意が必要な異常はありません。
`network.status`	`SUSPICIOUS`	ネットワーク情報に注意が必要です	ネットワーク情報に注意が必要なリスクがあります。
`network.status`	`DECEPTIVE`	ネットワーク情報は高リスクです	ネットワーク情報に明確な高リスクの兆候があります。

Pro 導入

Pro は Lite と同じ Imprint、サーバー専用 Secret 境界、共通 Endpoint を使います。プラン変更時に Endpoint を変更する必要はありません。Enterprise は現時点で Pro 契約を返します。

report 照会

リクエスト例

GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <your_pro_key>
Accept: application/json

History は Pro と Enterprise のみ利用できます。

リクエスト例

GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?days=7&recent=20
X-API-Key: <your_pro_key>
Accept: application/json

リクエスト例

GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?from=2026-03-01&to=2026-03-18&recent=20
X-API-Key: <your_pro_key>
Accept: application/json

バックエンド言語

SDK インストール / 依存

npm install @echoscan/echoscan

サーバー照会例

import { createProClient } from '@echoscan/echoscan'

const echoscan = createProClient({
  apiKey: process.env.ECHOSCAN_PRO_KEY
})

const report = await echoscan.getReport(imprint)
console.log(report.risk.status, report.risk.reasons)
const history = await echoscan.getHistory(imprint, { days: 7 })

SDK インストール / 依存

go get github.com/echoscan/echoscan-go@latest

サーバー照会例

package main

import (
	"context"
	"log"
	"os"

	echoscan "github.com/echoscan/echoscan-go"
)

func main() {
	imprint := "imp_0123456789abcdef0123456789abcdef"
	days := 7
	echoscanClient, err := echoscan.NewProClient(os.Getenv("ECHOSCAN_PRO_KEY"))
	if err != nil {
		log.Fatal(err)
	}
	report, err := echoscanClient.GetReport(context.Background(), imprint)
	if err != nil {
		log.Fatal(err)
	}
	history, err := echoscanClient.GetHistory(context.Background(), imprint, echoscan.HistoryQuery{Days: &days})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("risk=%v history=%v", report["risk"], history["summary"])
}

SDK インストール / 依存

pip install echoscan

サーバー照会例

import os
from echoscan import EchoScanProClient

imprint = "imp_0123456789abcdef0123456789abcdef"
echoscan_client = EchoScanProClient(os.environ["ECHOSCAN_PRO_KEY"])
report = echoscan_client.get_report(imprint)
history = echoscan_client.get_history(imprint, days=7)
print(report["risk"]["status"], report["risk"]["reasons"], history["summary"])

SDK インストール / 依存

[dependencies]
echoscan = "0.2.1"

サーバー照会例

use std::env;
use echoscan::{HistoryQuery, ProClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let imprint = "imp_0123456789abcdef0123456789abcdef";
    let api_key = env::var("ECHOSCAN_PRO_KEY")?;
    let echoscan = ProClient::new(&api_key)?;
    let report = echoscan.get_report(imprint).await?;
    let history = echoscan.get_history(imprint, HistoryQuery::Days { days: 7, recent: None }).await?;
    println!("{} {}", report["risk"]["status"], history["summary"]);
    Ok(())
}

オプション：Account Map を有効化（Pro）

Account Map は、次のような確認に利用できます。

現在のデバイスに関連付けられたアカウント数
現在のアカウントが使用したデバイス数
現在のアカウントとデバイスが過去にも同時に現れたか
1 台のデバイスに短時間で多数の新しいアカウント関係が生じているか
アカウント共有やアカウント乗っ取りの可能性があるか

Pro のサーバー側 Report 照会で、安定した内部ユーザー ID を渡します。

Node.js

リクエスト例

const report = await pro.getReport(imprint, {
  accountRef: currentUser.id
})

Go

リクエスト例

report, err := pro.GetReportWithOptions(
	context.Background(),
	imprint,
	echoscan.ReportOptions{AccountRef: currentUser.ID},
)
if err != nil {
	return err
}

Python

リクエスト例

report = pro.get_report(
    imprint,
    account_ref=current_user.id,
)

Rust

リクエスト例

let report = pro
    .get_report_with_options(
        imprint,
        ReportOptions { account_ref: Some(current_user.id.clone()) },
    )
    .await?;

Account Map は完全に任意です。accountRef には、安定した非機密かつ不変の内部ユーザー主キーを使用してください。メールアドレス、電話番号、氏名、ニックネーム、変更可能なユーザー名は送信しないでください。Account の関係は Workspace ごとに分離されます。

accountRef を省略すると、既存の Report リクエストと戻り値は変わりません。Account Map v1 は risk.status を自動変更しません。関係シグナルは独自の業務ルールと組み合わせて使用してください。

同時実行または遅延した関連付けの整合性

Account Map の統計には、レスポンス生成時点で完了し参照可能な関係だけが含まれます。

同時実行された POST のレスポンスは、まだ完了していない別の関係を先取りできません。

同時実行または遅延した関連付けがすべて完了すると、その後の GET はサーバーのイベント順序（recorded_at、次に event_id）で履歴統計を再計算します。

早いイベントは自身の履歴境界を維持し、遅いイベントはその境界以前に参照可能となった関係を含みます。

Account Map 戻り値例：

戻り値例

{
  "account_map": {
    "account_seen_before": true,
    "relationship_seen_before": false,
    "accounts_on_device": 7,
    "devices_on_account": 2,
    "accounts_first_seen_on_device_1h": 4
  }
}

フィールド	意味
`account_seen_before`	今回のアクセスより前に、現在の Workspace のいずれかのデバイスでこのアカウントが現れたかを示します。
`relationship_seen_before`	今回のアクセスより前に、このアカウントと現在のデバイスが同時に現れたかを示します。
`accounts_on_device`	現在のデバイスに関連付けられた重複しないアカウント数です。今回の関係も含みます。
`devices_on_account`	現在のアカウントに関連付けられた重複しないデバイス数です。今回の関係も含みます。
`accounts_first_seen_on_device_1h`	過去 1 時間に現在のデバイスとの関係が初めて作られたアカウント数です。登録完了フローで `accountRef` を送る場合は新規登録数の近似値として利用できます。ログイン時だけ送る場合は EchoScan が初めて観測したアカウントを数えるため、アカウントが直前に作成されたことを保証しません。

Pro report

Pro は Lite の厳密な上位集合で、デバイス継続性時刻、製品レベル Reason、任意のネットワーク詳細、Recent Activity を追加します。

戻り値例

{
  "schema_version": "1.0",
  "imprint": "imp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-28T01:30:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": true,
    "access_count": 42,
    "first_seen_at": "2026-06-10T03:20:00Z",
    "previous_seen_at": "2026-07-27T08:40:00Z"
  },
  "risk": {
    "status": "DECEPTIVE",
    "reasons": [
      "BROWSER_VERSION_MISMATCH",
      "PROXY_DETECTED",
      "NETWORK_INCONSISTENT"
    ]
  },
  "browser": {
    "status": "DECEPTIVE",
    "name": "Google Chrome",
    "version": "145"
  },
  "operating_system": {
    "status": "PASS",
    "name": "Windows",
    "version": "11"
  },
  "network": {
    "status": "DECEPTIVE",
    "observed_ip": "198.23.233.104",
    "country_code": "US",
    "alternate_ip": "126.234.173.23",
    "ip_consistency": "MISMATCH",
    "proxy_detected": true,
    "location": {
      "country_name": "United States",
      "region": "Illinois",
      "city": "Elk Grove Village",
      "timezone": "America/Chicago"
    },
    "provider": "Example Hosting Provider",
    "connection_type": "proxy",
    "asn": 36352
  },
  "activity": {
    "5m": {
      "events": 2,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 8,
      "distinct_ips": 2,
      "distinct_countries": 2
    },
    "24h": {
      "events": 21,
      "distinct_ips": 4,
      "distinct_countries": 3
    }
  }
}

Pro の PASS Report でも空の Reasons 配列を明示的にシリアライズします。

戻り値例

{
  "risk": {
    "status": "PASS",
    "reasons": []
  }
}

各フィールドの返却条件と有限な Machine Value の意味は、以下の表にまとめています。

製品リスク Reason

Reason	意味
`BROWSER_VERSION_MISMATCH`	ブラウザーバージョン情報に不整合があります
`BROWSER_IDENTITY_MISMATCH`	ブラウザー識別情報に不整合があります
`OS_ENVIRONMENT_MISMATCH`	OS 環境情報に不整合があります
`AUTOMATION_DETECTED`	自動化アクセスを検出しました
`ENVIRONMENT_INCONSISTENT`	現在のデバイス環境情報に不整合があります
`PROXY_DETECTED`	プロキシまたは VPN のリスクを検出しました
`HOSTING_NETWORK_DETECTED`	ホスティングサービスまたはデータセンターネットワークからのアクセスです
`NETWORK_INCONSISTENT`	ネットワーク ID 情報に不整合があります
`LOCATION_INCONSISTENT`	位置関連情報に不整合があります
`SIGNAL_DATA_INCOMPLETE`	今回の検査に必要な重要データが不完全です

Reason はリスク分類を表し、重大度は表しません。重大度は risk.status だけで表します。

Pro 専用フィールド

フィールド	返却条件	意味
`device.first_seen_at`	Pro で結果がある場合に UTC で返却します。	現在の Workspace がこのデバイスを最初に確認した時刻です。
`device.previous_seen_at`	Pro で常に返却します。初回アクセス時は `null` です。	今回のアクセス前に、このデバイスを最後に確認した時刻です。
`risk.reasons`	Pro で常に返却します。`PASS` の場合は空配列 `[]` です。	今回のリスク結果に対応する製品レベルの理由分類です。
`network.alternate_ip`	Pro で結果がある場合に返却します。	EchoScan が検出したクライアントのグローバル IP アドレス。
`network.ip_consistency`	Pro で常に返却します。	クライアントのグローバル IP とリクエスト送信元のグローバル IP の整合性結果です。
`network.proxy_detected`	Pro で結果がある場合に返却します。	プロキシまたは VPN のリスクを検出したかを示します。
`network.location`	Pro で結果がある場合に返却します。	リクエスト送信元のグローバル IP に対応するネットワーク位置情報です。
`network.location.country_name`	`network.location` の返却時に結果がある場合に返却します。	リクエスト送信元のグローバル IP に対応する国または地域名です。
`network.location.region`	`network.location` の返却時に結果がある場合に返却します。	リクエスト送信元のグローバル IP に対応する地域または第一行政区画です。
`network.location.city`	`network.location` の返却時に結果がある場合に返却します。	リクエスト送信元のグローバル IP に対応する都市です。
`network.location.timezone`	`network.location` の返却時に結果がある場合に返却します。	リクエスト送信元のグローバル IP のネットワーク位置に対応するタイムゾーンです。
`network.provider`	Pro で結果がある場合に返却します。	リクエスト送信元のグローバル IP が属するネットワーク組織またはサービスプロバイダーです。
`network.connection_type`	Pro で結果がある場合に返却します。	リクエスト送信元のグローバル IP が属するネットワーク種別です。
`network.asn`	Pro で結果がある場合に返却します。	リクエスト送信元のグローバル IP が属する自律システム番号です。
`activity`	Pro で結果がある場合に返却します。	現在のデバイスに関する直近のアクセス状況です。
`activity.5m`	`activity` の返却時に常に返却し、今回のアクセスを含みます。	現在のデバイスに関する直近 5 分間のアクセス状況です。
`activity.5m.events`	対応する期間の返却時に常に返却します。	この期間内のアクセス回数です。
`activity.5m.distinct_ips`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる IP アドレスの数です。
`activity.5m.distinct_countries`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる国または地域の数です。
`activity.1h`	`activity` の返却時に常に返却し、今回のアクセスを含みます。	現在のデバイスに関する直近 1 時間のアクセス状況です。
`activity.1h.events`	対応する期間の返却時に常に返却します。	この期間内のアクセス回数です。
`activity.1h.distinct_ips`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる IP アドレスの数です。
`activity.1h.distinct_countries`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる国または地域の数です。
`activity.24h`	`activity` の返却時に常に返却し、今回のアクセスを含みます。	現在のデバイスに関する直近 24 時間のアクセス状況です。
`activity.24h.events`	対応する期間の返却時に常に返却します。	この期間内のアクセス回数です。
`activity.24h.distinct_ips`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる IP アドレスの数です。
`activity.24h.distinct_countries`	対応する期間の返却時に常に返却します。	この期間内に確認された異なる国または地域の数です。

Pro 有限値の説明

フィールド	値	タイトル	意味
`network.ip_consistency`	`MATCH`	IP 情報は整合しています	ネットワーク IP 情報は整合しています。
`network.ip_consistency`	`MISMATCH`	IP 情報に不整合があります	ネットワーク IP 情報に不整合があります。
`network.ip_consistency`	`UNKNOWN`	明確な結果はありません	現在、明確な IP 整合性結果はありません。
`network.proxy_detected`	`true`	リスクを検出しました	プロキシまたは VPN のリスクを検出しました。
`network.proxy_detected`	`false`	リスクは検出されていません	プロキシまたは VPN のリスクは検出されていません。
`network.connection_type`	`residential`	住宅向けネットワーク	住宅向けブロードバンドネットワークです。
`network.connection_type`	`mobile`	モバイルネットワーク	モバイル通信事業者のネットワークです。
`network.connection_type`	`corporate`	企業ネットワーク	企業または組織のネットワークです。
`network.connection_type`	`hosting`	ホスティングネットワーク	クラウド、サーバーホスティング、またはデータセンターのネットワークです。
`network.connection_type`	`proxy`	中継ネットワーク	プロキシ、VPN、または同様の中継ネットワークです。
`network.connection_type`	`unknown`	未分類	現在、明確なネットワーク種別に分類されていません。

Pro history

History API は Pro と Enterprise のみ利用できます。

戻り値例

{
  "imprint": "imp_33333333333333333333333333333333",
  "range": {
    "from": "2026-03-01",
    "to": "2026-03-18",
    "days": 18
  },
  "summary": {
    "events": 12,
    "truncated": false,
    "firstSeenAt": "2026-03-01T08:10:00+09:00",
    "lastSeenAt": "2026-03-18T21:34:00+09:00"
  },
  "timeline": [
    {
      "date": "2026-03-01",
      "count": 2
    },
    {
      "date": "2026-03-18",
      "count": 3
    }
  ],
  "recent": [
    {
      "at": "2026-03-18T21:34:00+09:00",
      "surface": "login"
    }
  ]
}

days と from/to は同時に使えません。from と to は YYYY-MM-DD 形式で両方指定します。

History フィールド説明

フィールド	意味
`imprint`	この History 照会に使った検査 Report ID
`range`	この History 照会に適用した期間
`range.from`	照会期間の開始日
`range.to`	照会期間の終了日
`range.days`	照会期間に含まれる暦日数
`summary`	選択期間の集計概要
`summary.events`	選択期間内の訪問 Event 総数
`summary.truncated`	返却上限により結果が打ち切られたか
`summary.firstSeenAt`	選択期間内で最も早い Event 時刻
`summary.lastSeenAt`	選択期間内で最も新しい Event 時刻
`timeline`	日付別の訪問回数一覧
`timeline.date`	Timeline Entry の暦日
`timeline.count`	その日に記録した訪問 Event 数
`recent`	直近の訪問 Event 一覧
`recent.at`	直近 Event の発生時刻
`recent.surface`	顧客が指定した業務 Surface ID

サーバー側決定

主要入力として risk.status を使い、アカウント、取引、業務コンテキストと組み合わせます。Pro では risk.reasons、ネットワーク詳細、Activity、History も利用できます。

JavaScript

const decision =
  report.risk.status === 'PASS'
    ? 'allow'
    : 'challenge'

return Response.json({ decision })

この allow / challenge 分岐は顧客側ポリシーの例です。EchoScan Report API v1 は recommended_action を返しません。

完全な Report はサーバー側に保持し、ブラウザには必要な業務結果だけを返します。

エラー構造

戻り値例

{
  "error": {
    "code": "auth_failed",
    "message": "Authentication failed"
  }
}

分岐には error.code を使い、error.message は表示テキストとして扱ってください。

エラーフィールド説明

フィールド	意味
`error`	公開エラーオブジェクト
`error.code`	サーバー側の分岐に使う安定した Machine Code
`error.message`	ログや画面表示に使えるエラー説明

AI と EchoScan MCP を接続

標準 MCP を使い、Codex、Claude Code、VS Code、またはその他の対応クライアントを EchoScan に直接接続します。Workspace へのアクセスが初めて必要になると、クライアントがブラウザー認可を開きます。

サーバー URL https://api.echoscan.org/mcp

接続方法を見る

クライアントを選択

ターミナルで一度実行し、ブラウザーで EchoScan の Workspace と権限を承認します。

Codex

codex mcp add echoscan --url https://api.echoscan.org/mcp

ターミナルで一度実行します。Claude Code は初回接続時にブラウザー認可を開始します。

Claude Code

claude mcp add --transport http echoscan https://api.echoscan.org/mcp

このサーバー設定を MCP 構成へ追加します。VS Code は初回利用時に認可を求めます。

VS Code

{
  "servers": {
    "echoscan": {
      "type": "http",
      "url": "https://api.echoscan.org/mcp"
    }
  }
}

以下の値で Streamable HTTP のリモートサーバーを作成します。MCP OAuth 対応クライアントは認可フローを自動検出します。

Other MCP client

Name: EchoScan
Transport: Streamable HTTP
URL: https://api.echoscan.org/mcp
Authentication: OAuth 2.1 + PKCE

現在の Tool は echoscan_get_report、echoscan_get_history、echoscan_get_usage です。現在の OAuth Scope は echoscan.report.lite、echoscan.report.pro、echoscan.history.read、echoscan.usage.read です。

AI が EchoScan の導入コードも変更する場合は、先に次を読ませてください。

https://echoscan.org/llms.txt
https://echoscan.org/docs/ai-context.md

これらは同じ公開 API 契約に基づいて保守され、整合性チェックで検証されます。MCP 認可で EchoScan API Key を AI クライアントへ貼り付ける必要はありません。

EchoScan API・導入ガイド

推奨フロー

1. 接続するウェブサイトを追加

2. サーバー用 API Key を保存

3. Browser Verifier をウェブページに導入

4. Imprint を生成して送信

5. バックエンドで Report を照会

6. 業務判断を適用

ブラウザで imprint を生成

Browser Verifier パラメータ

サーバーへ送信

Lite 導入

report 照会

Lite report

フィールド説明

有限値の説明

Pro 導入

report 照会

オプション：Account Map を有効化（Pro）

Node.js

Go

Python

Rust

同時実行または遅延した関連付けの整合性

Pro report

製品リスク Reason

Pro 専用フィールド

Pro 有限値の説明

Pro history

History フィールド説明

サーバー側決定

エラー構造

エラーフィールド説明

AI と EchoScan MCP を接続

AI を EchoScan に接続