EchoScan Browser Verifier
EchoScan Browser Verifier runs in the browser to support pre-login device trust and browser
fingerprinting. It uses a publishable Browser Environment ID to return a server-issued imprint;
your trusted backend then queries EchoScan Report API v1 and applies your business policy.
Device identity compatibility
Versions 2.x and 3.x use the same device identity namespace and require a compatible service supporting the v4 submission API. Existing history remains available; devices from releases before 2.0 are not automatically recognized or merged into this namespace.
If device identification is unavailable, the run fails without submitting an imprint. This technical failure does not establish risk.
SDK 3.0 diagnostic boundary
Version 3.0 removes the getLastRunTrace() method exposed by published 2.x,
along with the previous detailed diagnostic and error exports.
run() returns imprint and an optional minimal diagnostic receipt;
SDK_VERSION identifies the installed SDK.
Failures use EchoScanError.category: cancelled, timeout, disposed, run_in_progress,
detection_failed, configuration or submission_failed. Failures also include SDK version and a minimal diagnostic receipt: not_sent (no correlated API request), unconfirmed (sent without receipt), or received (durable server receipt observed), with its API operation. An ID never grants diagnostic access. Original errors, response bodies,
causes, precise deadlines and internal identity failure reasons are not public contracts.
Remove trace exports and old error-class checks before migrating. The matching backend must deploy
first. For support, provide the SDK version, public error category and minimal diagnostic receipt.
These support details do not replace the formal Report or determine risk.
Install
npm install @echoscan/[email protected]
Create a Browser Environment in EchoScan, register the exact Allowed Origin where the verifier will
run, and copy its publishable environmentId. The Environment ID is not a Secret API Key or
Workspace ID.
Generate an imprint
import { createEchoScan } from '@echoscan/browser-verifier'
const verifier = createEchoScan({
environmentId: 'env_0123456789abcdef0123456789abcdef',
})
const { imprint } = await verifier.run()
A successful run returns imprint and may include a minimal diagnostic receipt. New imprints use the imp_<32 lowercase hex> format. Send
the imprint to your trusted backend with the protected sign-in, registration, payment, or other
business request.
Your backend uses its server-only Secret API Key to query Report API v1:
GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <server-secret-api-key>
Accept: application/json
Never place a Secret API Key or Workspace ID in browser code. Keep the full Report and final allow, challenge, review, or deny decision on your backend.
ESM, UMD, and CDN
The npm package provides ESM, TypeScript declarations, and a single-file UMD build exposed as
window.EchoScan. When self-hosting the ESM build, publish its matching chunks/ directory too.
EchoScan also serves the current supported CDN builds at:
- ESM:
https://cdn.echoscan.org/v1/echoscan.esm.js - UMD:
https://cdn.echoscan.org/v1/echoscan.umd.js
Documentation
- Developer API and integration guide
- OpenAPI contract
- EchoScan platform overview
- Public Scan — a first-party product demonstration, not a replacement for a customer Browser Environment or trusted-backend integration.