Browser Fingerprint API

EchoScan’s Browser Fingerprint API is an integration path for online services that need device continuity and access-risk context before a sensitive action. Browser Verifier collects and submits signals from the current browser environment and returns a server-issued { imprint }; the customer’s backend uses a Secret API Key to retrieve the base Report shared by Lite and Pro. This separation is designed for signup, login, trial issuance, API key creation, checkout, and other server-controlled decisions without exposing report credentials to browser code.

How the integration works

1. Create a Browser Environment in Console and configure its exact Allowed Origins.
2. Add Browser Verifier to the customer-controlled page and configure the publishable Environment ID.
3. Call run() for the protected action and receive { imprint } after the browser submission completes.
4. Send the Imprint to the customer’s backend with the actual signup, login, quota, or transaction request.
5. Query GET /api/v1/fingerprint/report/{imprint} from server-executed code with a Secret API Key.
6. Combine risk.status and the available report fields with the customer’s account, payment, entitlement, and verification data.

The customer backend owns the final allow, challenge, review, or deny action. EchoScan does not return a customer-specific recommended_action.

Why Browser Verifier returns only an Imprint

The Imprint is a server-issued report identifier, not the full device report and not a reusable secret. Returning this small value lets the browser attach device context to an existing business request while keeping the protected report exchange on the backend.

The full Report can contain device, browser, operating-system, network, continuity, and activity context. It belongs beside the customer’s other server-side evidence, where policy can account for false-positive cost and the meaning of the protected action.

Environment ID and Secret API Key boundary

An Environment ID has the form env_<32 lowercase hex>. It is publishable and identifies a configured browser deployment. EchoScan checks the request Origin against the Browser Environment’s exact allowlist. An Environment ID cannot read Reports, query History, or manage a Workspace.

A Secret API Key authenticates Report and History requests. It must stay in server-executed code or a secret manager. Do not put it in browser bundles, public environment variables, HTML, localStorage, logs, or client requests.

Browser Environments and Secret API Keys are separate resources. Rotating a key does not change the Environment ID, and disabling an Environment does not revoke a key.

Lite and Pro Reports

Lite and Pro use the same base Report structure, covering device continuity, current-visit risk and reasons, browser, operating system, network, and recent activity. Optional fields depend on available signals and data.

• Lite and Pro both support History and optional Account Map, including new links and existing snapshot reads. Pro provides higher request allowances, rate limits, and Browser Environment capacity. History queries a specified time range; the continuity summary and recent activity in the base Report are available in both plans.
• Public risk statuses are PASS, SUSPICIOUS, and DECEPTIVE.

Start with Lite to evaluate the base Report in your business policy. Choose Pro for higher request limits, rate limits, or Browser Environment capacity.

Signal categories and suitable actions

EchoScan evaluates groups of browser, device, rendering, network, and automation signals. The Report presents stable business-facing results rather than internal detector names, weights, thresholds, or bypass conditions.

This context can support registration, login, free-trial or credit issuance, API key creation, password reset, checkout, coupon redemption, voting, form submission, and other actions whose final decision already runs on a backend. Different actions should use different policies: a suspicious password reset and a suspicious newsletter signup do not carry the same cost.

Node, Go, Python, and Rust entry points

The server HTTP API is the baseline integration and works from any backend that can send an authenticated HTTPS request. Optional server SDKs provide the same Report path for Node.js, Go, Python, and Rust. Browser collection remains the responsibility of @echoscan/browser-verifier.

Use the developer documentation for current package names, installation commands, request examples, response fields, and error handling. Keep example placeholder routes separate from official EchoScan endpoints.

What the API cannot prove

A browser fingerprint is not a legal identity, a biometric identity, or proof that one person controls a device. Shared computers, virtualized environments, privacy features, software updates, hardware changes, and network changes can alter the observed context. A returning device is not automatically a trusted person, and a changed device is not automatically an attacker.

EchoScan also does not prove fraud or intent. Treat the result as one source of context and combine it with account history, payment state, entitlements, verification, request frequency, and the consequences of a false positive.

Next step

Open the developer documentation to connect Browser Verifier and Report API v1. To inspect the categories presented by the first-party experience before integrating, run the public Browser Fingerprint Scan.

Browser fingerprint API questions

What does the Browser Fingerprint API return to browser code?

Browser Verifier returns only a server-issued { imprint }. The customer sends that value to its backend, where a Secret API Key can query Report API v1.

Can an Environment ID read a device report?

No. The Environment ID is a publishable browser deployment identifier checked against exact Allowed Origins. It cannot authenticate Report or History requests.

Does a fingerprint identify a person with certainty?

No. EchoScan provides device continuity and access-risk context. It does not prove a person's legal identity, intent, or fraud, and the customer owns the final business decision.