Server-side integration

This is the in-app layer of the Cloudflare integration. The Cloudflare Worker already calls /trace at the edge before every monitored request reaches you, but the edge doesn’t know who the user is yet. This backend call adds the real subject_user_id and confirmed outcome status, which unlocks per-user signals the edge cannot see: velocity.user.*, ip.is_new_country_for_user, device.is_new_for_user, and ip.impossible_travel.

Complete the Cloudflare integration before adding this layer. The Worker injects the fingerprint script automatically and attaches the device token to every request as the x-tn-device-token header, so no frontend work is required on your end.

When to call it

Call /trace from your backend at the moment you authenticate the user: after you verify credentials but before you issue a session. This is when you have:

The real user ID (subject_user_id), which the edge never has
The confirmed outcome (succeeded or failed): the edge infers this from HTTP status codes, but you know it precisely
The device token, already on the incoming request as x-tn-device-token

Getting the device token

The Cloudflare Worker injects trace.min.js first-party onto your pages. That script calls /identify and then attaches the resulting device token to every subsequent request as the x-tn-device-token header. You don’t add any frontend code; just read the header your backend already receives:

TypeScript

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

Python

device_token = request.headers.get("x-tn-device-token")

Read the device token from the header

The Worker has already attached it. Extract it before you do anything else.

app.post("/login", async (req, res) => {
  const deviceToken = req.headers["x-tn-device-token"] as string | undefined;
  const { email, password } = req.body;

  // Verify credentials first
  const user = await verifyCredentials(email, password);
  const loginStatus = user ? "succeeded" : "failed";

@app.post("/login")
async def login(request: Request, body: LoginBody):
    device_token = request.headers.get("x-tn-device-token")
    
    # Verify credentials first
    user = await verify_credentials(body.email, body.password)
    login_status = "succeeded" if user else "failed"

POST to /trace with subject_user_id and confirmed status

Send the real user ID (even on failure, if you resolved the account) and the confirmed outcome.

  const ip =
    (req.headers["x-forwarded-for"] as string)?.split(",")[0].trim() ??
    req.headers["x-real-ip"] as string;

  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: loginStatus,
      ip,
      email,
      device_token: deviceToken,
      subject_user_id: user?.id ?? null,
    }),
  }).then((r) => r.json());

    # Get the real client IP from the forwarded header
    forwarded_for = request.headers.get("x-forwarded-for")
    ip = forwarded_for.split(",")[0].strip() if forwarded_for else request.headers.get("x-real-ip")

    trace = httpx.post(
        "https://api.tracenow.io/trace",
        headers={"Authorization": f"Bearer {os.environ['TRACENOW_SECRET_KEY']}"},
        json={
            "event": "login",
            "status": login_status,
            "ip": ip,
            "email": body.email,
            "device_token": device_token,
            "subject_user_id": str(user.id) if user else None,
        },
    ).json()

Switch on the verdict

allow → proceed, challenge → require step-up, deny → block.

  switch (trace.verdict) {
    case "allow":
      if (!user) return res.status(401).json({ error: "Invalid credentials" });
      return res.json({ session: await issueSession(user) });

    case "challenge":
      // Surface step-up — MFA, CAPTCHA, OTP, etc.
      // You decide the mechanism; Tracenow just tells you a challenge is needed.
      return res.status(200).json({
        requires_challenge: true,
        challenge_type: "mfa",
        trace_id: trace.trace_id,
      });

    case "deny":
      return res.status(403).json({ error: "Access denied" });
  }
});

    verdict = trace.get("verdict")

    if verdict == "allow":
        if not user:
            return JSONResponse({"error": "Invalid credentials"}, status_code=401)
        return JSONResponse({"session": await issue_session(user)})

    elif verdict == "challenge":
        # Surface step-up to the client — MFA, CAPTCHA, OTP, etc.
        return JSONResponse({
            "requires_challenge": True,
            "challenge_type": "mfa",
            "trace_id": trace.get("trace_id"),
        })

    elif verdict == "deny":
        return JSONResponse({"error": "Access denied"}, status_code=403)

Getting the real client IP

Pass the real client IP, not your server’s outbound address. Extract it from the forwarded headers set by your reverse proxy or load balancer.

const ip =
  (req.headers["x-forwarded-for"] as string)?.split(",")[0].trim() ??
  (req.headers["x-real-ip"] as string);

import { headers } from "next/headers";

const ip =
  headers().get("x-forwarded-for")?.split(",")[0].trim() ??
  headers().get("x-real-ip") ??
  undefined;

forwarded_for = request.headers.get("x-forwarded-for")
ip = forwarded_for.split(",")[0].strip() if forwarded_for else request.headers.get("x-real-ip")

Never use req.socket.remoteAddress (Node) or request.remote_addr (Python/WSGI) in a proxied environment, as these return your load balancer’s IP, not the user’s.

Handling signals_complete: false

On a first-time lookup for a new IP or email (a cache miss), some async enrichment may not have resolved before the response returns. The signals_complete: false flag tells you the verdict was made on partial data. For most checkpoints this is fine: your policies still evaluated on what was available, and the result is usually correct. For high-stakes decisions (transaction approval, privileged action), retry with the same payload after ~500 ms to get the warm-cache result:

TypeScript

let trace = await callTrace(payload);

if (!trace.signals_complete && isHighStakes) {
  await new Promise((resolve) => setTimeout(resolve, 500));
  trace = await callTrace(payload);
}

What the in-app call adds

Signal group	Cloudflare edge	In-app call
IP enrichment	Yes	Yes
Email enrichment	Yes	Yes
Phone enrichment	Yes	Yes
Device fingerprint	Yes	Yes
`velocity.ip.*`	Yes	Yes
`velocity.user.*`	No (no user ID)	Yes
`ip.is_new_country_for_user`	No	Yes
`ip.impossible_travel`	No	Yes
`device.is_new_for_user`	No	Yes
Confirmed `status`	Inferred from HTTP code	Exact

Cloudflare integration: set this up first
POST /trace reference: full request and response documentation
Verdicts: what allow, challenge, and deny mean and when each applies

Getting started

Core concepts

Integration

Use cases

API reference

Server-side integration

When to call it

Getting the device token

Getting the real client IP

Handling signals_complete: false

What the in-app call adds

​When to call it

​Getting the device token

​Full login example

​Getting the real client IP

​Handling signals_complete: false

​What the in-app call adds

​Related

When to call it

Getting the device token

Full login example

Getting the real client IP

Handling signals_complete: false

What the in-app call adds

Related