# EchoScan AI Integration Context

Last updated: 2026-08-11

This guide is for coding agents integrating EchoScan into an application. The Developer API, OpenAPI contract, and linked MCP and Agent API guides remain authoritative for their respective execution surfaces.

## Product definition

EchoScan is a device identity and access-risk service. Browser Verifier runs in a real browser, produces an Imprint, and sends it to trusted server code. The server uses a Secret API Key to retrieve a Lite or Pro Report and applies the customer's own allow, challenge, review, or deny policy.

The publishable Environment ID identifies a Browser Environment and allowed Origin. It is not a Secret API Key or Workspace ID.

## Published Research Evidence

Browser Fingerprint Stability Study v1.0 contains 94 valid measurements across 3 device environments and 8 Device / Browser combinations.

- Canonical Chinese report: https://echoscan.org/pages/browser-fingerprint-stability-zh-CN.html
- Machine-readable Research JSON: https://echoscan.org/research/browser-fingerprint-stability/research-summary.json
- Aggregate CSV: https://echoscan.org/research/browser-fingerprint-stability/results-summary.csv

Published findings:

- Persistent device identity remained generally consistent across the tested browser restart, site-data clearing, network-change, and private-browsing conditions.
- Firefox, Safari, Windows Laptop Chrome, and Brave showed session-context identity changes in the tested environments.
- In the tested Brave environment, the ordinary-window context recovered after two independent Private sessions, while the two Private sessions formed distinct, internally stable context states.
- Device continuity, browser session context, and Network Status behaved as separate information dimensions in the tested environments.

These findings apply only to the tested environments. The study does not provide a global accuracy benchmark, an overall false-positive rate, an overall false-negative rate, or Network Status accuracy.

## Browser Verifier

Install the browser package:

```bash
npm install @echoscan/browser-verifier
```

Run it in browser-executed code with the publishable Environment ID:

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

const echoscan = createEchoScan({
  environmentId: 'env_0123456789abcdef0123456789abcdef',
})

const { imprint } = await echoscan.run()
```

Send the Imprint with the application's protected action to trusted server code. Do not send a Workspace ID or Secret API Key from browser code.

## Server HTTP API

Server code authenticates with `X-API-Key`.

Lite or Pro Report:

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

The authenticated key plan selects Lite or Pro depth.

History:

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

History also accepts an explicit `from` and `to` date range according to the Developer API contract.

## SDKs

Server SDKs are optional wrappers over the same HTTP contract.

- Browser Verifier: `@echoscan/browser-verifier`
- Node server SDK: `@echoscan/echoscan`
- Go server SDK: `github.com/echoscan/echoscan-go`
- Python server SDK: `echoscan`
- Rust server SDK: `echoscan`

Keep the Secret API Key in the server runtime or secret manager.

## Report contracts

Lite Report includes the Imprint, creation time, device continuity summary, `risk.status`, browser summary, operating-system summary, and a minimized network summary.

Pro is a strict superset of Lite. It adds `risk.reasons`, continuity timestamps, detailed network context, activity aggregates, and History access.

Primary decision fields:

- `risk.status`: `PASS`, `SUSPICIOUS`, or `DECEPTIVE`
- `risk.reasons`: Pro product reasons defined by the Developer API contract

EchoScan returns evidence. The customer owns the final business decision.

## Account Map

Account Map is optional. When used, `accountRef` must be a stable, non-sensitive, immutable internal primary key. Do not send email addresses, phone numbers, real names, nicknames, or mutable usernames. Account relationships are isolated by Workspace and do not automatically change `risk.status`.

## Error shape

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

Branch on `error.code`; treat `error.message` as display or log text.

## Production MCP connection

The production remote MCP endpoint is `https://api.echoscan.org/mcp` and uses Streamable HTTP with OAuth 2.1 Authorization Code + PKCE S256.

OAuth discovery:

- Protected Resource Metadata: https://api.echoscan.org/.well-known/oauth-protected-resource/mcp
- Authorization Server Metadata: https://api.echoscan.org/.well-known/oauth-authorization-server

Human users sign in, select one Workspace, review requested scopes, and authorize the MCP client. Membership, entitlements, rate limits, and monthly quota are revalidated when tools run.

Tools:

- `echoscan_get_report`
- `echoscan_get_history`
- `echoscan_get_usage`

OAuth scopes:

- `echoscan.report.lite`
- `echoscan.report.pro`
- `echoscan.history.read`
- `echoscan.usage.read`

Connection instructions for Codex, Claude Code, VS Code, and generic MCP clients are in the [MCP guide](https://echoscan.org/docs/mcp-en-US.md).

## Agent API discovery

Machine clients discover availability and purchase terms through the live product catalog and OpenAPI contract.

- API Catalog: https://echoscan.org/.well-known/api-catalog
- OpenAPI: https://echoscan.org/openapi.json
- Product catalog: https://api.echoscan.org/api/v1/agent/products
- Agent API guide: https://echoscan.org/pages/agent-api-en-US.html

The Agent Trial is a machine-purchased credential contract and remains separate from human OAuth MCP Workspace authorization.

## Security checklist

- Run Browser Verifier only in a real allowed browser Origin.
- Treat the Environment ID as publishable and every API key as secret.
- Keep report retrieval and business decisions in trusted server code.
- Never put API keys, OAuth tokens, claim tokens, or payment credentials in URLs, prompts, browser persistence, logs, metrics, or committed files.
- Return only the minimum decision data required by browser code.
- Revoke and rotate compromised keys and authorizations through their documented lifecycle.
- Preserve Workspace isolation when using Report, History, Usage, MCP, or Account Map.