EchoScan API・導入ガイド

Browser Verifier がブラウザーで信号を収集・送信します。Submit が成功すると EchoScan サーバーが発行した imprint が返り、バックエンドが正式な Report を照会します。

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

コマンドラインでの設定は CLI 連携をご覧ください。

推奨フロー

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

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

Console の最初のウェブサイト設定を開き、Browser Verifier を実行するウェブサイトを入力します。例は https://shop.example.com です。Console が URL から scheme・host・port を抽出し、Path・Query・Fragment を除いた正確な Origin を保存し、Web App と既定のサーバー API Key を 1 つのトランザクションで作成します。作成後、公開可能な env_... Environment ID をコピーします。

サイトを起動する前でも localhost:3000、127.0.0.1:8000、[::1]:3000 を保存できます。Console はこれらのループバックアドレスに HTTP、通常のドメインに HTTPS を補います。明示した HTTP(S) は保持し、保存する正確な Origin をプレビューします。ローカル接続後はウェブサイト接続で元のサイト詳細を開き、アドレスを追加を選んで、ローカルアドレスを残したまま新しい行に公開先を追加して保存します。Environment ID と既存のサーバー Key は変わりません。アドレスの追加だけでは接続完了になりません。各サイトで実際の Submit を行い、顧客バックエンドが同じ Imprint の Report を取得する必要があります。

既存の無料プランをローカル接続に利用できます。ブラウザ Submit とサーバーリクエストは現行プランの各ルールで別々に計量され、ローカルと公開サイトに同じルールが適用されます。データは同じ Workspace に保存されます。

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

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

導入の成功とは、ブラウザーで実際の Submit が完了し、バックエンドが同じ imprint に対応する有効な Report を取得できることです。SUSPICIOUS や DECEPTIVE でも取得は成功です。収集や照会の失敗はリスク状態と分けて処理してください。

Imprint を取得して送信

Direct mode では env_<32 lowercase hex> 形式の environmentId が必須です。Browser Verifier はフィンガープリントの Submit と診断相関情報を持つ公開鍵リクエストで使用し、Workspace ID を受け付けません。API key や Authorization もブラウザーへ置きません。

インストール
npm install @echoscan/browser-verifier@3.0.5
JavaScript
import { createEchoScan } from '@echoscan/browser-verifier'

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

npm と CDN のどちらかを選びます。CDN を使う場合も、次の独立した ESM と UMD のコードブロックはどちらか一方だけを使用してください。照会先のサンプルパスは自社バックエンドで実装します。

CDN:ESM(いずれか一方)

リクエスト例
<script type="module">
  import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js'

  const sdk = createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    // Continue with the minimal business result from your backend.
  } catch {
    // Collection or lookup failed: stop this action; offer a controlled retry.
  } finally {
    sdk.dispose()
  }
</script>

CDN:UMD(いずれか一方)

リクエスト例
<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
(async () => {

  const sdk = window.EchoScan.createEchoScan({
    environmentId: 'env_0123456789abcdef0123456789abcdef'
  })
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    // Continue with the minimal business result from your backend.
  } catch {
    // Collection or lookup failed: stop this action; offer a controlled retry.
  } finally {
    sdk.dispose()
  }
})()
</script>

run() は imprint と任意の最小 diagnostic 受領情報を返します。新しい 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 です。保護対象の業務アクションと一緒に送信します。

Browser Verifier の 1 回の実行を調べる

以下の例は Browser Verifier 3.0.5 向けです。ブラウザーと配信する SDK アセットには同じバージョンを使用してください。

公開済み 2.x の getLastRunTrace() と詳細な Error クラスの export は削除します。サポートには SDK_VERSION、EchoScanError.category、最小の diagnostic 受領情報だけを使います。direct profile の not_sent は相関 ID を持つ API リクエストが未開始、unconfirmed は ID を送信したものの一致する受領情報が未確認、received は対象 API 操作の永続化された受領情報を確認済み、という意味です。未確認のリクエストにはサーバー記録がない場合があります。ID は参照権限を与えません。

リクエスト例
import { createEchoScan, SDK_VERSION, EchoScanError } from '@echoscan/browser-verifier'

const sdk = createEchoScan({ environmentId: 'env_0123456789abcdef0123456789abcdef' })
try {
  const { imprint } = await sdk.run()
  // Send imprint to your server; only the server queries the business Report.
  await fetch('/api/echoscan/report', {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ imprint, sdkVersion: SDK_VERSION })
  })
} catch (error) {
  const category = error instanceof EchoScanError ? error.category : 'integration_failed'
  const support = { sdkVersion: SDK_VERSION, category,
    diagnostic: error instanceof EchoScanError ? error.diagnostic : null }
  // Provide only this safe summary to support. No automatic diagnostic upload.
  void support
} finally {
  sdk.dispose()
}

サポート担当者は最小の診断受領情報を使い、権限のある範囲で記録済みのリクエストと正式 Report を関連付けます。受領情報にはブラウザーの完全な実行状況は含まれず、未確認のリクエストにはサーバー記録がない場合があります。

Imprint は管理された業務フロー内で扱い、完全な Report は顧客サーバーに保管します。元のエラー、指紋、IP、Key、Cookie、パラメーター付き URL をコピーしないでください。技術的な失敗はリスク判定ではなく、情報の不足だけでリスクがあるとは判断できません。

Submit や Report 取得の失敗は技術エラーであり、リスク判定ではありません。業務ルールに従って操作を保留または拒否してください。回復可能な技術エラーだけを回数制限付きで再試行し、PASS になるまで検出を繰り返さないでください。取得に成功した SUSPICIOUS や DECEPTIVE は評価済みの結果です。許可、追加認証、レビュー、拒否は自社の業務情報と合わせて判断します。challenge の認証は自社で実装し、資格判定、冪等性、重複発行防止は顧客バックエンドが担当します。

サーバーへ送信

業務 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 ではありません。

最小構成の完全な導入例

Node.js 22.22 またはサポート対象の 22.x、pnpm、npm 公開版の Browser Verifier を使用します。以下は独立したデモプロジェクトです。既存のプロジェクトに導入する場合は、元の設定を保持し、必要なコードだけを組み込んでください。最初に Console で http://localhost:3000 を追加してください。実際の Environment ID は .env.local、Secret は .env.server に設定し、どちらもバージョン管理から除外します。

package.json

戻り値例
{
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1 --port 3000 --strictPort",
    "server": "node --env-file=.env.server server.mjs"
  },
  "dependencies": {
    "@echoscan/browser-verifier": "3.0.5",
    "ajv": "8.20.0",
    "ajv-formats": "3.0.1"
  },
  "devDependencies": {
    "vite": "7.3.6"
  }
}

index.html

HTML
<button id="verify" type="button">Verify visit</button>
<p id="result" role="status"></p>
<script type="module" src="/main.js"></script>

main.js

リクエスト例
import { createEchoScan } from '@echoscan/browser-verifier'

const sdk = createEchoScan({ environmentId: import.meta.env.VITE_ECHOSCAN_ENVIRONMENT_ID })
const button = document.querySelector('#verify')
const result = document.querySelector('#result')
button.addEventListener('click', async () => {
  button.disabled = true
  result.textContent = 'Checking…'
  try {
    const { imprint } = await sdk.run()
    const response = await fetch('/api/echoscan/report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ imprint })
    })
    if (!response.ok) throw new Error('Report lookup failed')
    const { decision } = await response.json()
    if (!['allow', 'challenge'].includes(decision)) throw new Error('Invalid decision')
    result.textContent = decision === 'allow' ? 'Report retrieved: allow' : 'Report retrieved: additional verification'
  } catch {
    result.textContent = 'Verification unavailable. Retry when ready.'
  } finally {
    button.disabled = false
  }
})
window.addEventListener('pagehide', () => sdk.dispose(), { once: true })

vite.config.js

JavaScript
export default {
  server: { proxy: { '/api/echoscan/report': 'http://127.0.0.1:3001' } }
}

server.mjs

リクエスト例
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import Ajv2020 from 'ajv/dist/2020.js'
import addFormats from 'ajv-formats'

const apiKey = process.env.ECHOSCAN_API_KEY
if (!apiKey) throw new Error('ECHOSCAN_API_KEY is required')
const contract = JSON.parse(await readFile(new URL('./openapi.json', import.meta.url), 'utf8'))
const ajv = new Ajv2020()
addFormats(ajv)
const validateReport = ajv.compile(contract.components.schemas['public.report.schema.json'])

createServer(async (request, response) => {
  const send = (status, body) => {
    response.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
    response.end(JSON.stringify(body))
  }
  if (request.method !== 'POST' || request.url !== '/api/echoscan/report') {
    send(404, { error: 'not_found' })
    return
  }
  let imprint
  try {
    let body = ''
    for await (const chunk of request) {
      body += chunk
      if (Buffer.byteLength(body) > 2048) throw new Error('Request too large')
    }
    imprint = JSON.parse(body).imprint
    if (typeof imprint !== 'string' || !/^imp_[0-9a-f]{32}$/.test(imprint)) throw new Error('Invalid imprint')
  } catch {
    send(400, { error: 'invalid_request' })
    return
  }
  try {
    const upstream = await fetch(`https://api.echoscan.org/api/v1/fingerprint/report/${imprint}`, {
      headers: { 'X-API-Key': apiKey, Accept: 'application/json' },
      signal: AbortSignal.timeout(5000)
    })
    if (!upstream.ok) {
      // HTTP failures never enter the risk decision branch.
      send(503, { error: 'verification_unavailable' })
      return
    }
    const report = await upstream.json()
    if (!validateReport(report) || report.imprint !== imprint) {
      send(503, { error: 'verification_unavailable' })
      return
    }
    if (report.risk.status === 'UNAVAILABLE') {
      send(503, { error: 'verification_unavailable' })
      return
    }
    const decision = report.risk.status === 'PASS' ? 'allow' : 'challenge'
    send(200, { decision })
  } catch {
    send(503, { error: 'verification_unavailable' })
  }
}).listen(3001, '127.0.0.1')

.gitignore

Text
.env.local
.env.server
node_modules/
dist/

.env.local

Text
VITE_ECHOSCAN_ENVIRONMENT_ID=env_0123456789abcdef0123456789abcdef

.env.server

Text
ECHOSCAN_API_KEY=<your_server_secret_key>
インストール
pnpm install
curl --fail --output openapi.json https://echoscan.org/openapi.json
pnpm server
# In a second terminal:
pnpm dev

両方を起動して http://localhost:3000 を開き、Verify visit を押します。ブラウザーで実際の Submit が完了すると、バックエンドは同じ Imprint を照会し、ダウンロード済みの正式な OpenAPI Report Schema で検証します。成功時は allow または challenge だけを返し、失敗時は利用不可と表示します。この例はログイン、決済、リソース提供を実行しません。既存の認証、認可、追加確認ポリシーを引き続き適用してください。openapi.json は明示的な準備手順で取得し、通常実行時にはリモート schema を取得しません。

Report 導入(Lite/Pro)

Lite と Pro は同じ基本 Report 構造を使います。以下の共通照会はアップグレード後も利用できます。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 バージョンの適用範囲

このページのサーバー SDK のインストールと呼び出し例は 0.2.4 に固定し、現在の Report、History、Account Map のパスを使用します。0.2.3 の Pro メソッドを備えたクライアントも同じ公開パスを使用し、必要なアクセス権を持つ Lite または Pro Key で利用できます。ただし、Lite クライアントは廃止済みの /api/v1/fingerprint/report-lite/{imprint} を呼び出すため、現在の基本 Report API には使えません。0.2.3 を使い続ける場合は、これらの操作に Pro クライアントを使用するか、0.2.4 に更新してください。クライアント名でプランは決まりません。

公開パッケージのインストール、インポート/ビルド、合成 HTTP の例は確認済みですが、すべての言語 SDK の本番接続を検証したことを意味しません。

バックエンド言語
SDK インストール / 依存
npm install @echoscan/echoscan@0.2.4
サーバー照会例
import { createLiteClient } from '@echoscan/echoscan'

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

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

**リクエストの計量。**ブラウザーの Submit は Browser Environment ごとに記録します。API Key と MCP の計量対象リクエストは Workspace のサーバー枠を共有します。計量対象のサーバー操作には、Report GET、Account Map POST、History GET など、適用される保護された API 操作 が含まれます。利用記録の段階に到達した呼び出しは、業務処理のエラーや同じ Imprint の再照会も含めて一回として数えます。その前の認証、レート、利用枠のチェックで拒否されたリクエストは、このサーバー利用量に入りません。同じ送信 ID によって重複と判定されたブラウザーの再送は、Submit 枠を再度消費しません。

Lite は UTC の暦月を使い、Pro Beta と有料 Pro は現在の権限またはサブスクリプション期間を使います。Key を追加しても枠は増えません。ブラウザー Submit とサーバー呼び出しは別の計量で、ユニーク訪問者数ではありません。現在の枠と期間は Console で確認してください。

正式 Report

Lite と Pro は同じ基本 Report 構造を使います。Enterprise Key も同じ正式な契約に従います。任意フィールドは、シグナルが取得できない場合や適用できるデータがない場合に省略されることがあります。

Report の内容 確認できること
識別子と時刻 どの検査に対応する Report か、いつ生成されたか。
デバイス継続性 Workspace 内の Device ID、再訪状態、累計アクセス回数、記録がある場合の初回・前回時刻。
現在のアクセスリスク 全体のリスク状態、製品レベルの理由、各理由のリスクレベル。
ブラウザーと OS 識別された名称、取得できたバージョン、それぞれのリスク状態。
ネットワーク 取得できた出口 IP、国や地域、プロキシの結果、ネットワーク整合性など。
最近の活動 データがある場合、直近 5 分、1 時間、24 時間のアクセス数、異なる IP 数、異なる国や地域の数。

初回記録では前回時刻が null になります。0、false、空のコレクション、null の意味を保持し、欠落フィールドは公開契約に従って処理してください。基本 Report の継続性の概要と最近の活動は、History API の指定期間の照会とは別の情報です。

通常アクセスの例:

戻り値例
{
  "schema_version": "1.0",
  "imprint": "imp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-28T01:30:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": false,
    "access_count": 1,
    "previous_seen_at": null
  },
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  },
  "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",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    }
  }
}

疑わしいアクセスの例:

戻り値例
{
  "schema_version": "1.0",
  "imprint": "imp_11111111111111111111111111111111",
  "created_at": "2026-07-28T01:35:00Z",
  "device": {
    "id": "did_C98D76E54F32",
    "seen_before": false,
    "access_count": 1,
    "previous_seen_at": null
  },
  "risk": {
    "status": "SUSPICIOUS",
    "reasons": [
      "SIGNAL_DATA_INCOMPLETE"
    ],
    "findings": [
      {
        "reason": "SIGNAL_DATA_INCOMPLETE",
        "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",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    }
  }
}

再訪デバイスの例:

戻り値例
{
  "schema_version": "1.0",
  "imprint": "imp_22222222222222222222222222222222",
  "created_at": "2026-07-28T02:00:00Z",
  "device": {
    "id": "did_A12B34C56D78",
    "seen_before": true,
    "access_count": 8,
    "first_seen_at": "2026-06-10T03:20:00Z",
    "previous_seen_at": "2026-07-27T08:40:00Z"
  },
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  },
  "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",
    "ip_consistency": "MATCH",
    "proxy_detected": false
  },
  "activity": {
    "5m": {
      "events": 1,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "1h": {
      "events": 2,
      "distinct_ips": 1,
      "distinct_countries": 1
    },
    "24h": {
      "events": 8,
      "distinct_ips": 2,
      "distinct_countries": 1
    }
  }
}

フィールド説明

フィールド 返却条件 意味
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 明確な高リスクの兆候があります 偽装、自動化、または高リスクネットワークの明確な兆候があります。 より厳格な認証、制限、または目視確認を行います。
risk.status UNAVAILABLE 判定不可 重要なデータが不足しているため、判定できません。 検証を利用できない旨を表示し、業務ルールに従って操作を保留または拒否してください。
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 ネットワーク情報は高リスクです ネットワーク情報に明確な高リスクの兆候があります。

History と Account Map(Lite/Pro)

Lite と Pro はどちらも History と任意の Account Map に対応し、新しい関連付けと既存スナップショットの読み取りを利用できます。サーバー発行の Imprint、サーバー専用 Secret 境界、Endpoint、基本 Report は共通です。Pro はリクエスト枠、レート上限、Browser Environment の容量を拡大します。

report 照会

基本 Report の照会は Report 導入 にまとめています。以下の SDK 例では、独立した History 操作も示します。

History は Lite と Pro の両方で利用できます。SDK の Lite/Pro という名前はメソッドの組み合わせを示し、Report 構造や必要なプランの違いを示すものではありません。必要なメソッドを持つクライアントと、有効な Workspace Key を使用します。

リクエスト例
GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?days=7&recent=20
X-API-Key: <your_server_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_server_key>
Accept: application/json
バックエンド言語
SDK インストール / 依存
npm install @echoscan/echoscan@0.2.4
サーバー照会例
import { createProClient } from '@echoscan/echoscan'

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

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

オプション:Account Map を有効化(Lite/Pro)

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

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

Lite と Pro の両方で新しい Account Map の関連付けを作成できます。サーバー側 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

リクエスト例
use echoscan::ReportOptions;

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

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

Report GET は、新しい accountRef を指定せずに、その Imprint の既存のスナップショットを読み取ることがあります。Account Map の関連付けと既存スナップショットの読み取りは別の操作です。Lite に戻ったことだけで既存スナップショットが消えるとは限りません。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 が初めて観測したアカウントを数えるため、アカウントが直前に作成されたことを保証しません。

Report の項目とリスク理由

正式 Report は常にこの項目モデルを使います。任意フィールドは公開契約、取得できたシグナル、適用できるデータに従います。account_map に既存のスナップショットが含まれる場合がありますが、毎回返るとは限りません。

戻り値例
{
  "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"
    ],
    "findings": [
      {
        "reason": "BROWSER_VERSION_MISMATCH",
        "status": "DECEPTIVE"
      },
      {
        "reason": "PROXY_DETECTED",
        "status": "DECEPTIVE"
      },
      {
        "reason": "NETWORK_INCONSISTENT",
        "status": "DECEPTIVE"
      }
    ]
  },
  "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
    }
  }
}

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

戻り値例
{
  "risk": {
    "status": "PASS",
    "reasons": [],
    "findings": []
  }
}

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

製品リスク Reason

Reason 意味
BROWSER_VERSION_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、各理由が寄与したリスクレベルは risk.findings の各項目で示します。

正式 Report の追加フィールド

フィールド 返却条件 意味
device.first_seen_at 結果がある場合に UTC で返却します。 現在の Workspace がこのデバイスを最初に確認した時刻です。
device.previous_seen_at 常に返却します。初回アクセス時は null です。 今回のアクセス前に、このデバイスを最後に確認した時刻です。
risk.reasons 常に返却します。PASS の場合は空配列 [] です。 今回のリスク結果に対応する製品レベルの理由分類です。
risk.findings 常に返却します。PASS の場合は空配列 [] です。 Report の判定に使われた理由と重大度の組です。
network.alternate_ip 結果がある場合に返却します。 EchoScan が検出したクライアントのグローバル IP アドレス。
network.ip_consistency 常に返却します。 クライアントのグローバル IP とリクエスト送信元のグローバル IP の整合性結果です。
network.proxy_detected 結果がある場合に返却します。 プロキシまたは VPN のリスクを検出したかを示します。
network.location 結果がある場合に返却します。 リクエスト送信元のグローバル 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 結果がある場合に返却します。 リクエスト送信元のグローバル IP が属するネットワーク組織またはサービスプロバイダーです。
network.connection_type 結果がある場合に返却します。 リクエスト送信元のグローバル IP が属するネットワーク種別です。
network.asn 結果がある場合に返却します。 リクエスト送信元のグローバル IP が属する自律システム番号です。
activity 結果がある場合に返却します。 現在のデバイスに関する直近のアクセス状況です。
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 対応する期間の返却時に常に返却します。 この期間内に確認された異なる国または地域の数です。
account_map 任意。既存スナップショットを取得できる場合や関連付け操作で返す場合に提供します。 この Imprint に対応する Workspace 内のアカウント関係。

ネットワークの有限値

フィールド 値 タイトル 意味 導入側の対応例
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 未分類 現在、明確なネットワーク種別に分類されていません。

History

History は Lite と Pro の両方で利用できる期間指定の照会です。基本 Report の継続性の概要とは分けて扱います。

戻り値例
{
  "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

検出データの削除

Workspace、Browser Environment、デバイス、アカウント単位で、現在の稼働中の検出データを削除します。処理は非同期で実行され、受付結果から状態を照会できます。

サーバー側で有効な Workspace Server API Key を X-API-Key に設定して呼び出します。その Workspace の通常のサーバー Key は、いずれも削除操作を実行できます。Browser Environment ID、Console Cookie、Agent Trial の認証情報、MCP 認可は使用できません。対象 Workspace は Key で決まり、本文に workspace_id は指定できません。HTTP API のみを提供し、サーバー SDK と Console には対応する削除操作がありません。

削除範囲を選ぶ

scope 選択条件 削除範囲
workspace 追加の選択条件なし 現在の Workspace の全検出履歴と関連データ。匿名訪問、Account Map の紐付け、Environment が記録されていない訪問を含みます。
environment environment_id が必須 指定した Browser Environment の全検出履歴と関連データ。匿名訪問を含み、Console の表示期間には限定されません。
device device_id が必須。environment_id は任意 選択範囲内のデバイスの訪問と関連データ。そのデバイス上の各アカウントによる訪問を含みます。
account account_ref が必須。environment_id は任意 Account Map 参照に明示的に紐付けた訪問と関連データ。同じデバイスや IP を理由に、紐付けのない訪問まで選択しません。

environment_id は Console のウェブサイト接続にある env_... を使います。無効化済み Environment も削除対象にできます。device_id は Report の device.id を使います。account_ref は Report の紐付け時と同じ安定した内部ユーザー ID を使います。デバイス・アカウントのリクエストで environment_id を省略すると、Workspace 全体の一致する履歴が対象になります。

削除には、選択した訪問に直接関連する検出記録、Account Map の紐付け、帰属を確認できるデバイスデータが含まれます。別 Workspace のデータは変更されません。共有デバイスデータや帰属不明のデータがある場合、リクエスト全体が review_required となり、部分的な削除は実行しません。

削除を申請する

POST /api/v1/data-deletions は HTTP 202 と受付結果を返します。HTTP 202 は受理を示し、完了は受付結果の status で確認します。

Browser Environment 単位:

リクエスト例
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}
フィールド ルール
request_id 必須。新しい操作ごとにランダムな 32 桁の小文字 16 進数 ID を生成し、送信前に永続保存します。再試行では元の ID を使います。サンプル ID は実際のリクエストに使いません。
scope 必須。workspace、environment、device、account のいずれか。
confirmation 必須。固定値 DELETE_LIVE_DATA。
environment_id environment では必須、device と account では任意、workspace では省略します。
device_id device の場合のみ使用し、account_ref と同時には指定できません。
account_ref account の場合のみ使用します。最大 256 バイトで、制御文字や前後の空白は使えません。

本文は最大 4096 バイトです。適用しないフィールドは省略します。null、重複フィールド、未定義のフィールドは受け付けません。

Workspace 単位:

リクエスト例
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "scope": "workspace",
  "confirmation": "DELETE_LIVE_DATA"
}

Browser Environment 内のデバイス単位:

リクエスト例
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "scope": "device",
  "device_id": "did_example_device_1",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}

Browser Environment 内のアカウント単位:

リクエスト例
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json

{
  "request_id": "cccccccccccccccccccccccccccccccc",
  "scope": "account",
  "account_ref": "EXAMPLE-customer-42",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "confirmation": "DELETE_LIVE_DATA"
}

受理時の受付結果:

戻り値例
{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "received_at": "2026-11-05T00:00:00Z",
  "copies_status": "not_verified"
}

処理結果を照会する

GET /api/v1/data-deletions/{requestId} は HTTP 200 と現在の受付結果を返します。同じ Workspace の現在有効な Server API Key を使います。requestId は申請前に保存した request_id です。

リクエスト例
GET https://api.echoscan.org/api/v1/data-deletions/0123456789abcdef0123456789abcdef
X-API-Key: <your_server_key>
Accept: application/json

HTTP 200 は受付結果の取得成功を示し、削除結果は status で確認します。数秒間隔でポーリングし、タイムアウトを設定します。タイムアウト後も、照会の再開やサポートへの確認に使うため元のリクエスト ID を保持します。

完了時の結果:

戻り値例
{
  "request_id": "0123456789abcdef0123456789abcdef",
  "scope": "environment",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "status": "live_data_deleted",
  "received_at": "2026-11-05T00:00:00Z",
  "finished_at": "2026-11-05T00:00:01Z",
  "copies_status": "not_verified",
  "deleted": {
    "visit_events": 12,
    "devices": 3
  }
}

削除結果のフィールド

フィールド 意味
request_id 削除リクエスト ID。
scope 申請した削除範囲。
environment_id Browser Environment を指定した場合に返されます。
status 現在の処理状態。
received_at リクエストの受信日時。
finished_at 処理終了日時。任意フィールド。
copies_status 固定値 not_verified。コピーの消去はこの API では確認されません。
reason レビューまたは実行失敗の理由コード。
deleted 成功時のデータ種別ごとの削除件数。対象が存在しない場合はゼロになることがあります。種別の件数は訪問者数ではありません。

状態とレビュー

status 意味と対応
queued 受理済み、または実行中です。照会を続けます。
live_data_deleted 選択範囲の現在の稼働中の検出データを削除しました。
review_required 削除は実行されていません。リクエスト ID と reason を添えてサポートに連絡します。
failed 削除は確定されず、処理は終了しました。原因を確認してから新規リクエストが必要か判断します。

レビュー理由は shared_device_data(共有デバイスデータ)、account_key_version_review(Account Map の紐付けの確認が必要)、ownership_review(データ帰属の確認が必要)です。実行失敗は execution_failed を使います。review_required と failed は終了状態で、自動再試行されません。

再試行とエラー

同じ request_id と対象で POST を再送すると元の受付結果が返り、削除は再実行されません。範囲や選択条件を変更すると競合になります。GET は対象を再送せずに元の受付結果を取得できます。

HTTP / error.code 対応
400 / invalid_deletion_request 範囲、フィールド、確認値を照合します。
401 / invalid_api_key サーバー Key が有効か確認します。
403 / data_deletion_forbidden その Workspace の通常のサーバー Key を使います。
404 / data_deletion_environment_not_found Environment が Key の Workspace に属するか確認します。
404 / data_deletion_not_found 現在の Workspace 内で受付結果が見つかりません。削除成功を示すものではありません。
409 / data_deletion_conflict 元の ID と対象を照合し、GET で元の結果を確認します。
429 / data_deletion_busy Retry-After: 10 に従います。Workspace ごとに待機中のリクエストは最大 1 件で、新規リクエスト間は最低 10 秒空けます。
429 / key_rate_limited リクエストとポーリングの頻度を下げます。
500 / data_deletion_failed 結果が未確認です。元の ID と選択条件で再試行します。
503 / data_deletion_unavailable 一時的に利用できません。元のリクエスト ID を保持します。

レスポンスが失われた場合も元の ID を再利用します。POST が繰り返し 503、GET が 404 を返す場合は自動再試行を止め、元の ID を添えてサポートに連絡します。未確認の結果を回避するために新しい ID を使わないでください。申請と照会は検出/Report のクォータを消費しませんが、通常のリクエスト頻度制限は適用されます。

保持されるデータ

Workspace、ログインアカウント、メンバー、Browser Environment 設定、API Key、インストール設定、OAuth 認可、請求、実際の使用量は保持されます。アカウントの退会と接続全体の Reset は別の操作です。

live_data_deleted が確認するのは現在の稼働中の検出データのみです。バックアップ、エクスポート、ログ、研究用コピーは確認対象外で、copies_status は not_verified のままです。コピーを含む削除依頼はサポートで個別に処理します。この状態はコピーの継続利用を許可するものではありません。

削除後も収集は可能です。テストデータを消す前に収集を一時停止し、live_data_deleted を待ってから新しい SDK 送信 ID で次のテストを開始します。今後の収集も停止する場合は、対応する Browser Environment を無効化するか、連携の呼び出しを停止してください。

サーバー側決定

risk.status、risk.reasons、risk.findings を Report 入力として使い、アカウント、取引、業務コンテキストと組み合わせます。ネットワーク詳細と Activity は正式 Report に含まれ、History は両プランで利用できる独立した期間指定の照会です。

JavaScript
if (report.risk.status === 'UNAVAILABLE') {
  return Response.json({ error: 'verification_unavailable' }, { status: 503 })
}

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

return Response.json({ decision })

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

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

エラー構造

戻り値例
{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid"
  }
}

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

エラーフィールド説明

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

失敗する段階と復旧

SDK 3.0 は EchoScanError.category と SDK バージョン、最小の相関受領情報を使います。message を解析したり、従来の詳細な Error/Transport クラスを import したりしません。

分類 意味と対応
configuration、run_in_progress、disposed 設定やライフサイクルを修正します。この拒否された呼び出しに新しい API 受領情報はありません。
detection_failed 送信可能な収集結果がありません。業務操作を保留または拒否します。
cancelled、timeout サーバーで受理された可能性があるため、受領状態で調査します。失敗は PASS ではありません。
submission_failed 通信、API 応答、検証の失敗です。安全な受領情報と分類をサポートに伝え、Report を捏造しません。

公開鍵 GET は一時的な失敗を規則に従って再試行します。Browser Verifier は Submit POST を自動再試行しません。再度の run() は新しい収集・送信で、前回の送信 ID を再利用する保証はありません。同じ ID と認識された重複 Submit は二重計上されませんが、新しい run は新たな利用量を消費する場合があります。

HTTP を直接使う場合は、成功契約を読む前にステータスを確認します。envelope の error.code で分岐し、通信/プロキシ障害が必ず JSON を返すとは仮定しません。invalid_api_key、origin_not_allowed、quota_exceeded、key_rate_limited に応じて認証情報、Origin、枠、待機時間を修正します。HTTP 成功時も Report 契約と同じ Imprint の検証が必要です。

**HTTP 503 quota_state_unavailable。**現在の利用枠の使用量を確実に読み取る、または確定することができず、保護された操作の実行前に停止したことを示します。一時的なサービスの可用性エラーであり、HTTP 429 quota_exceeded とは異なります。利用枠を使い切ったという判定ではありません。検証を一時的に利用できないと表示し、PASS に進めないでください。サービス復旧後、設定した回数の上限内で GET を再試行し、継続的なポーリングを避けてください。Key の変更やプランのアップグレードでは、この障害は解消しません。障害が続く場合は、HTTP ステータス、公開エラーコード、リクエスト識別子をサポートへ伝え、Key や Report 全体は記録しないでください。書き込みの応答が不明な場合は、既存のスナップショットを確認してから再送を判断します。

サーバー SDK は 0.2.3 と 0.2.4 で別途正規化します。Node は EchoScanApiError.code/serverCode、Go は APIError.Code/ServerCode、Python は ApiError.code/server_code、Rust は ApiError.code/server_code です。この 503 の正規化 code は upstream_unavailable で、サーバーエラーコードのフィールドには quota_state_unavailable が残ります。HTTP ステータス、リクエスト識別子、再試行フィールドは各言語の公開型に従います。インストール済みバージョンの公開 SDK 型を確認してください。

サーバー SDK の GET は設定上限まで一時的な失敗を再試行できます。計上段階に達した再試行や重複 Report GET は、業務エラーでも利用量を消費する場合があります。それより前の認証・レート・枠による拒否は計上しません。Account Map POST は書き込みなので、不明な応答のまま無条件に再試行したりアカウント参照を変更したりしません。いずれの失敗も PASS 分岐へ進めません。

AI と EchoScan MCP を接続

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

REMOTE MCP SERVER

AI を EchoScan に接続

このリモート URL を一度追加するだけです。アクセスが必要になるとクライアントが EchoScan の認可画面を開き、AI クライアントへ API Key を貼り付ける必要はありません。

Streamable HTTP OAuth 2.1 + PKCE
サーバー URL https://api.echoscan.org/mcp
接続方法を見る
クライアントを選択

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

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

主要ツール(概要)は echoscan_get_report、echoscan_get_history、echoscan_get_usage です。ツールと OAuth scope の完全な一覧、有効化条件、呼び出し権限は MCP ガイドを参照してください。この概要は全ツールの一覧ではありません。

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

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

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

CLI 連携

コマンドラインで EchoScan の接続設定を作成し、接続状態を確認します。Node.js 22.22 以降の 22.x が必要です。プロジェクトのディレクトリで実行してください:

インストール
npx @echoscan/cli init --origin https://example.com

ブラウザーで EchoScan CLI を認可し、Workspace を選択します。設定の作成後、推奨フローに沿って Browser Verifier とバックエンドを接続し、接続状態を確認してください:

インストール
npx @echoscan/cli status
npx @echoscan/cli verify

status は現在の接続状態を表示します。verify はブラウザーとサーバーの両方が接続済みの場合に成功します。CLI は接続設定を作成します。SDK のインストールやアプリケーションコードの変更は行いません。

npm パッケージと README