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 observes the current browser environment and returns a server-issued { imprint }; the customer’s backend uses a Secret API Key to retrieve a Lite or Pro Report. 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 Report API v1 endpoint. The authenticated key plan determines the response depth.

• Lite returns the Device ID, seen_before, access_count, overall risk.status, and core browser, operating-system, and network results.
• Pro adds product risk reasons, first and previous seen times, detailed network context, recent activity windows, and access to History.
• Public risk statuses are PASS, SUSPICIOUS, and DECEPTIVE.

Start with the information required by the business policy. A workflow that only routes non-passing visits to an extra verification step may begin with Lite. Investigation or explanation workflows may need the additional Pro context.

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.