> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprintiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

Understanding FingerprintIQ's multi-layered identification approach.

## Architecture

FingerprintIQ uses a **two-tier fingerprint** approach for maximum accuracy and stability. Rather than relying on a single hash that breaks when any signal changes, it separates signals into a stable core and a fuzzy supporting layer.

```mermaid
flowchart TD
    A[Browser] -->|Collects 41 browser signals in parallel| B[FingerprintIQ SDK]
    B -->|Single POST request| C[Cloudflare Edge Worker]
    C -->|Extract edge signals| D{Signal Processing}
    D --> E[TLS Fingerprint]
    D --> F[ASN Classification]
    D --> G[Geo Coherence]
    D --> H[Header Order]
    D --> I[UA Consistency]
    E & F & G & H & I --> J[Core Hash Computation]
    J --> K{Visitor Lookup}
    K -->|Match found ≥60% similarity| L[Returning Visitor\nIncrement visit count]
    K -->|No match| M[New Visitor\nCreate visitor record]
    L & M --> N[Return compact response\nrequestId + verdicts + scores]
    N --> A
    N --> O[(Events Store\nFull signals persisted)]
    O -->|GET /v1/events/:requestId| P[Your Backend Server]
```

The entire identification flow — from signal collection to response — completes in under 200 ms for most devices, including the Cloudflare edge round-trip.

## The Two-Tier Fingerprint

### Tier 1: Stable Core Hash

A small set of high-stability hardware and engine signals form the primary lookup key. If a visitor's core hash matches an existing record, FingerprintIQ proceeds to similarity scoring.

| Signal | Source | Stability |
|--------|--------|-----------|
| WebGL Renderer | GPU hardware model | Very High |
| WebGL Vendor | GPU manufacturer | Very High |
| Navigator | CPU cores, platform, languages | Very High |
| Screen | Resolution + pixel ratio | High |
| Math Hash | JS engine precision quirks | Very High |
| Error Messages | JS engine error string format | Very High |
| CSS Property Count | Browser engine version | High |
| Platform Features | Available API surface | High |

The core hash is computed entirely from hardware and engine characteristics — not from any mutable state like cookies, localStorage, or IP address.

### Tier 2: Supporting Signals (Similarity Score)

Additional signals compute a **similarity score** (0.0 – 1.0) to handle edge cases where one or two core signals might shift due to a browser update or system change.

| Signal | Type | Match Method |
|--------|------|-------------|
| Canvas Hash | Rendering | Exact |
| Audio Hash | Rendering | Exact |
| DOMRect Hash | Measurement | Exact |
| Font Count | Enumeration | 10% tolerance |
| WASM Timing | Performance | 10% tolerance |
| Speech Hash | System voices | Exact |
| Intl Hash | Locale formatting | Exact |
| SVG Hash | SVG rendering | Exact |
| Codec Hash | Media support | Exact |
| Timezone | System clock | Exact |

### Fuzzy Matching Algorithm

**Compute Core Hash**

Hash the 7 stable signals into a deterministic lookup key.
  **Lookup Existing Visitors**

Query stored visitor records that share the same core hash.
  **Score Similarity**

Compare supporting signals between the new visit and each candidate record. Compute a similarity percentage.
  **Threshold Decision**

If similarity is 60% or above, it's the same visitor — increment the visit count and return the existing `visitorId`. If below 60%, create a new visitor record.

The 60% similarity threshold means up to 4 supporting signals can change simultaneously (e.g., after a major browser update) before FingerprintIQ creates a new visitor record.

## Compact Response + Server API

FingerprintIQ uses a **two-tier data model**: the client gets a compact response for fast decision-making, while full signal data is available server-side for audit and advanced analysis.

### What `identify()` returns

The identify endpoint returns a compact response with everything needed for real-time decisions:

- `requestId` — unique event identifier for server-side lookup
- `visitorId` — stable device identifier
- `verdicts` — per-signal boolean results (bot, VPN, Tor, proxy, incognito, tampering, headless, VM, devtools, privacy browser, high activity, IP blocklist)
- `suspectScore` — composite 0–100 risk score
- `botProbability`, `confidence` — top-level scores
- `ip` and `ipLocation` — network metadata

Raw signals (all 41 browser signals and full edge/server analysis) are **not** included in the identify response.

### Accessing Full Signal Data

Pass the `requestId` from the client to your backend, then call the Events API to retrieve the full event including all raw signals:

```typescript
// Client side — pass requestId to your server
const result = await fiq.identify();
// POST result.requestId to your backend

// Server side — retrieve full event
const res = await fetch(
  `https://fingerprintiq.com/v1/events/${requestId}`,
  { headers: { 'Authorization': 'Bearer fiq_secret_your_key' } }
);
const event = await res.json();
// event.signals.client — all 41 browser signal results
// event.signals.server — edge-derived signals and analyses
```

This architecture keeps raw signal data off the client. The browser only ever sees the verdict — not the evidence. This prevents fingerprint spoofing by making it impossible for the client to know exactly which signals are failing.

## Edge Network Analysis

In addition to the 41 browser signals, FingerprintIQ extracts signals and derived analyses from the HTTP request at the Cloudflare edge. These are captured during the TLS handshake and TCP connection — before any JavaScript runs. They depend on the OS networking stack and TLS implementation, not on what the browser reports about itself.

Core edge analyses include:

- **JA4 TLS fingerprint** — derived from the ClientHello cipher suite ordering, extensions, and supported versions
- **ASN classification** — whether the IP belongs to a residential ISP, mobile carrier, datacenter, VPN provider, or Tor exit node
- **RTT geo coherence** — the round-trip time to the nearest Cloudflare PoP vs. the expected latency for the claimed IP location
- **HTTP fingerprinting** — header order and protocol behavior that identify the network stack
- **UA consistency checks** — compares claimed browser identity against TLS and HTTP evidence

**TLS Fingerprint details**

Every TLS connection begins with a ClientHello message containing cipher suite preferences, extension list, and protocol versions. This combination is characteristic of the client's TLS implementation — Chrome, Firefox, and Safari each produce distinct TLS fingerprints. FingerprintIQ captures the cipher suite, TLS version, HTTP protocol (HTTP/2 vs HTTP/3), ClientHello length, and JA4 hash.

**ASN Classification details**

Every IP address belongs to an Autonomous System (AS). FingerprintIQ classifies each ASN into a category: Residential ISP, Mobile Carrier, Datacenter, Commercial VPN, Tor Exit Node, Education, Government, or CDN. Datacenter and Tor classifications significantly increase bot probability.

**Geo Coherence details**

Cross-validates the claimed IP location against network timing. The TCP round-trip time to the nearest Cloudflare colo is compared against the expected RTT based on the claimed city. A coherence score below 0.3 suggests a VPN or proxy is in use — the user's true location differs from their IP.

## Bot Detection

The bot probability score (0.0 – 1.0) combines multiple weighted indicators. A score above 0.5 warrants a CAPTCHA challenge; above 0.7 warrants blocking.

| Factor | Weight | Description |
|--------|--------|-------------|
| Datacenter ASN | +0.25 | Traffic from cloud providers (AWS, GCP, Azure) |
| Tor Exit Node | +0.30 | Traffic routed through Tor |
| Software Renderer | +0.25 | SwiftShader, LLVMpipe, Mesa — headless GPU |
| Headless Markers | +0.35 | WebDriver flag, Puppeteer/Playwright signatures |
| API Tampering | +0.20 | Modified browser APIs detected via integrity check |
| Missing Signals | +0.30 | No canvas, WebGL, or audio — stripped APIs |
| UA/TLS Mismatch | +0.30 | User-Agent doesn't match TLS fingerprint |

Bot scores are additive and can exceed 1.0 before clamping. A headless browser running through a datacenter with a spoofed UA will score near 1.0 across all indicators simultaneously.