How it works

tracenow protects your app at two layers: an edge layer (no code, via Cloudflare) and an in-app layer (one backend call). Both layers call the same /trace endpoint. Together they cover every attack surface: bots and bad inputs at the door, per-user account-takeover signals inside your app.

The two layers

Edge (no code)

A managed Cloudflare Worker on your zone intercepts every login, signup, and OTP before it reaches your app. It injects the device fingerprint script, extracts signals, and calls /trace. On deny, it blocks at the edge. No code required.

In-app (one call)

After you authenticate the user, call /trace from your backend with the real subject_user_id and confirmed status. This unlocks per-user signals the edge can never see: new device for this account, impossible travel, per-user failed-login velocity.

The edge cannot know who is logging in because the user isn’t authenticated yet. The in-app call fills that gap with one small backend call after authentication.

Layer	When it runs	Has `subject_user_id`	Can block at the edge
Edge (Cloudflare Worker)	Before your app receives the request	No (falls back to email as key)	Yes, on `deny`
In-app (`/trace` from backend)	After you authenticate the user	Yes	No, you enforce in your app

You can start with the edge today (no code, no deploy) and add the in-app call later. The device token is already on the request as x-tn-device-token, so there’s nothing extra to wire up on the frontend.

Architecture

                        ┌─────────────────────────────────────────┐
                        │          Your Cloudflare Zone            │
                        │                                          │
  Browser               │   ┌─────────────────────────────────┐   │
  ─────────────────────►│   │      tracenow Worker            │   │
  POST /login           │   │  1. inject trace.min.js         │   │
                        │   │  2. read email/phone/IP         │   │
  ◄─────────────────────│   │  3. POST /trace ─────────────►  │   │
  loads trace.min.js    │   │  4. verdict returned            │   │
                        │   │  5. deny → block here (403)     │   │   api.tracenow.io
  POST /identify        │   │     allow/challenge → forward ──┼───┼──► enrich + evaluate
  ◄─────────────────────│   └─────────────────────────────────┘   │    policies → verdict
  device token (dv_...) │                      │                   │
                        │                      ▼                   │
                        │              ┌───────────────┐           │
                        │              │  Your Origin  │           │
                        │              │  (your app)   │           │
                        │              └───────────────┘           │
                        │                      │                   │
                        └──────────────────────┼───────────────────┘
                                               │
                                    POST /trace (in-app)
                                    ├── subject_user_id: "usr_123"
                                    ├── status: "succeeded"
                                    └── device_token: from x-tn-device-token header

Request lifecycle (edge layer)

Here is the full sequence for a protected route in Enforce mode.

Browser                  Cloudflare Worker            api.tracenow.io       Your Origin
   │                            │                            │                    │
   │── POST /login ────────────►│                            │                    │
   │                            │                            │                    │
   │◄── 200 + <script> ─────────│ (1) inject trace.min.js   │                    │
   │    (served first-party     │     served from your domain│                    │
   │     from your own domain)  │                            │                    │
   │                            │                            │                    │
   │── POST /identify ──────────┼───────────────────────────►│                    │
   │◄── { device_token } ───────┼────────────────────────────│                    │
   │                            │                            │                    │
   │── POST /login ─────────────│ (2) next request carries   │                    │
   │   x-tn-device-token: dv_.. │     the device token       │                    │
   │                            │ (3) extract email, phone,  │                    │
   │                            │     IP, device_token       │                    │
   │                            │── POST /trace ────────────►│                    │
   │                            │◄── { verdict: "deny" } ────│                    │
   │                            │                            │                    │
   │                            │ (4a) verdict = deny        │                    │
   │◄── 403 ────────────────────│     block here             │                    │
   │                            │                            │                    │
   │                            │ (4b) verdict = allow/challenge                  │
   │                            │──────────────── forward to origin ─────────────►│
   │◄──────────────────────────────────────────── response from origin ───────────│
   │                            │                            │                    │
   │                            │ (5) outcome trace (async)  │                    │
   │                            │     maps HTTP response code│                    │
   │                            │     → succeeded/failed     │                    │
   │                            │── POST /trace (status) ───►│                    │

What happens at each step

Inject trace.min.js

The Worker serves the device fingerprint script from a path on your own domain. The script runs in the browser, collects device signals (canvas, timing, automation indicators), and calls /identify.

Classify the event

The Worker checks if the request matches a configured route and method. GET requests are not monitored by default. Matched requests are classified as login, signup, or otp.

Extract signals and call /trace

The Worker reads the email/phone from the request body, the IP from headers, and the device token from x-tn-device-token (or tn_device_token form field). It calls POST /trace synchronously (Enforce mode) or asynchronously (Monitor mode).

Enforce the verdict

In Enforce mode: deny → return the configured block response (default 403, or a custom status, redirect, or body). allow and challenge → forward to origin. In Monitor mode: always forward; the trace is logged.

Outcome trace (async, non-blocking)

After the origin responds, the Worker fires a second /trace call to record the real outcome, mapping the HTTP response code to succeeded or failed. This is what powers failed-login velocity rules at the edge. It does not block the user.

The Cloudflare Worker cannot render your app’s MFA or CAPTCHA flow. A challenge verdict is always forwarded to your origin. Handle step-up friction in your app. Only deny blocks at the edge.

Fail-open

If /trace is slow or unreachable, the Worker forwards the request to your origin without enforcing. tracenow never breaks your site.

The device-token round-trip

Device fingerprinting is stateful: the injected script collects signals, fetches a device token from /identify, and the browser attaches that token to every subsequent same-origin request automatically, as the x-tn-device-token header or tn_device_token form field. You never manage this. The Worker injects the script, the script fetches the token, and the token arrives at your server as a request header. When you make the in-app /trace call, you just read it off:

const deviceToken = req.headers["x-tn-device-token"];

The device token lets tracenow recognize the same physical device across sessions and users. This is what powers device.is_new_for_user, device.automation_detected, and velocity.device.distinct_user_ids_24h.

How /identify and /trace relate

/identify and /trace are two distinct calls with distinct purposes:

Call	Who makes it	When	What it does
`/identify`	The injected `trace.min.js` script (browser)	On page load of a protected route	Collects device signals, returns a `device_token`
`/trace`	The Cloudflare Worker (and optionally your backend)	On a login/signup/otp event	Evaluates all signals against policies, returns a `verdict`

You never call /identify yourself. The Worker injects the script that calls it. The device token the script receives is what you (or the Worker) forward to /trace as device_token.

In-app layer: the one call that adds per-user depth

Call POST /trace from your backend after authenticating the user. Pass the real subject_user_id and the confirmed status. These are things the edge will never know.

TypeScript (Node)

const deviceToken = req.headers["x-tn-device-token"];

const trace = await fetch("https://api.tracenow.io/trace", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRACENOW_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event: "login",
    status: loginSucceeded ? "succeeded" : "failed",
    subject_user_id: user.id,    // the real account — the edge never has this
    email: user.email,
    ip: clientIp,
    device_token: deviceToken,   // arrived on the request automatically
  }),
}).then((r) => r.json());

switch (trace.verdict) {
  case "allow":     return issueSession(user);
  case "challenge": return requireMfa(user);
  case "deny":      return res.status(403).json({ error: "Blocked" });
}

Per-user signals that only unlock here:

device.is_new_for_user: this device has never been seen for this account
ip.is_new_country_for_user: login from a country this user has never used
ip.impossible_travel: physically impossible to have moved between the last location and this one
velocity.user.*: counts scoped to this specific user ID

Where to go next

Verdicts

What allow, challenge, and deny mean, and how to handle each in your app.

Cloudflare integration

Connect Cloudflare, configure route rules, and deploy the Worker.

Rules and policies

Build conditions that trigger challenge or deny: fields, operators, logic.

Server-side integration

The full in-app /trace contract, every field, and verdict handling patterns.

Getting started

Core concepts

Integration

Use cases

API reference

The two layers

Edge (no code)

In-app (one call)

Architecture

Request lifecycle (edge layer)

What happens at each step

Fail-open

The device-token round-trip

How /identify and /trace relate

In-app layer: the one call that adds per-user depth

Where to go next

Verdicts

Cloudflare integration

Rules and policies

Server-side integration

​The two layers

Edge (no code)

In-app (one call)

​Architecture

​Request lifecycle (edge layer)

​What happens at each step

​Fail-open

​The device-token round-trip

​How /identify and /trace relate

​In-app layer: the one call that adds per-user depth

​Where to go next

Verdicts

Cloudflare integration

Rules and policies

Server-side integration

The two layers

Architecture

Request lifecycle (edge layer)

What happens at each step

Fail-open

The device-token round-trip

How /identify and /trace relate

In-app layer: the one call that adds per-user depth

Where to go next