Verdicts

Every /trace call returns a verdict. There are exactly three. Your code (and the Cloudflare Worker) switches on this value to enforce the outcome.

{
  "trace_id": "tr_...",
  "verdict": "allow",
  ...
}

The three verdicts

Verdict	Meaning	Where it’s enforced
`allow`	No policy matched (nothing suspicious)	Proceed normally
`challenge`	A policy matched with a soft action	Step-up in your app (MFA, CAPTCHA, OTP)
`deny`	A policy matched with a hard block	Block the request (403 or redirect)

allow is the default. It means every rule in your policies evaluated the signals and nothing triggered. There is no block value. The correct term is deny.

allow

No rule matched. The user passed every condition in every policy. Proceed normally: issue a session, complete the transaction, send the OTP.

if (trace.verdict === "allow") {
  return issueSession(user);
}

challenge

A rule matched and its action is challenge. Add friction, but don’t hard-block. Use this for situations where you want the user to prove they’re human before you let them continue: a new device on a known account, a VPN login, a slightly suspicious email domain. challenge means “make them work for it.” The specific mechanism is up to you: MFA, CAPTCHA, email OTP, SMS verification.

Handling challenge in your app

The canonical pattern is a requires_challenge flag in your response body that your frontend interprets:

TypeScript (Node)

switch (trace.verdict) {
  case "allow":
    return issueSession(user);

  case "challenge":
    // Don't issue a session yet. Tell the frontend to show step-up.
    return res.status(200).json({
      requires_challenge: true,
      challenge_type: "mfa",   // or "captcha", "otp" — your choice
    });

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

Your frontend reads requires_challenge and redirects to your MFA or CAPTCHA flow. After the user completes step-up, call /trace again with the same signals plus status: "succeeded" if they passed. This second trace records the real outcome and re-evaluates against your policies.

After the user completes step-up, send a second /trace call with status: "succeeded". This updates the velocity counters and lets status-dependent rules (like “succeeded login from new country”) evaluate correctly.

Challenge types

MFA (authenticator app, hardware key)

Best for account-takeover signals (new device, impossible travel, new country). The user already has an authenticator enrolled. Redirect to your existing MFA flow.

CAPTCHA

Best for bot/automation signals such as device.is_headless, device.automation_detected, and high velocity. A CAPTCHA distinguishes a real human from a script. Use any provider (hCaptcha, reCAPTCHA, Turnstile).

Email or SMS OTP

Best for new-device or low-trust scenarios where the user doesn’t have MFA enrolled. Sends a one-time code to the address or phone number on the account.

deny

A rule matched and its action is deny. Hard block: don’t issue a session, don’t process the transaction, don’t send the OTP. Return an error.

if (trace.verdict === "deny") {
  return res.status(403).json({ error: "Access denied" });
}

Edge behavior: what the Worker does

The Cloudflare Worker enforces verdicts differently from your backend, because it sits in front of your app and can’t render your MFA flow.

Verdict	Edge behavior	In-app behavior
`allow`	Forward to origin	Proceed normally
`challenge`	Forward to origin	Return `requires_challenge`, handle step-up
`deny`	Block here (return configured response)	Return 403

The critical difference: at the edge, only deny blocks. challenge is always forwarded to your origin. The Worker cannot render your MFA page or CAPTCHA (that lives in your app), so challenge enforcement is always the in-app call’s job.

If you rely solely on the edge (no in-app /trace call), a challenge verdict will reach your origin as a normal forwarded request with no enforcement. To actually enforce challenge, you need the in-app call. See Server-side integration.

This is intentional and correct. Think of it as division of responsibilities:

The edge handles deny (bots, Tor, known-bad IPs, disposable emails): hard blocks before your app sees a single byte.
Your app handles challenge (step-up friction for real users who look slightly suspicious).

Configuring the deny response at the edge

In Enforce mode, you configure what the Worker returns on deny. The default is a 403 with an empty body. You can override it per route rule:

Override type	Use it when
Custom status code	You want a different HTTP status (e.g. 401)
302 redirect URL	You want to send blocked users to a page
Custom HTML body	The route serves a browser page
Custom JSON body	The route is an API/XHR endpoint

When a policy is triggered

When verdict is challenge or deny, the response includes a policy object telling you exactly which rule fired:

{
  "trace_id": "tr_...",
  "verdict": "deny",
  "policy": {
    "id": "pol_...",
    "name": "Block credential stuffing",
    "action": "deny",
    "rule_id": "rul_...",
    "rule_name": "High failed-login velocity from IP"
  },
  "signals": {
    "decision": {
      "rule_id": "rul_...",
      "rule_name": "High failed-login velocity from IP",
      "logic": "AND",
      "matched_conditions": []
    }
  }
}

Use policy.rule_name for logging. Avoid showing it to the user, as it reveals your detection logic.

When no rule matches

When verdict is allow, the policy object is absent from the response. signals_complete: true means all enrichment resolved. If signals_complete: false, some async enrichment was still pending and the verdict was made on partial data. For high-stakes decisions, retry after ~500 ms to get the warm-cache result.

Full verdict handling pattern

TypeScript (Node)

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,
    email: user.email,
    ip: clientIp,
    device_token: req.headers["x-tn-device-token"],
  }),
}).then((r) => r.json());

switch (trace.verdict) {
  case "allow":
    // Nothing matched. Issue the session.
    return issueSession(user);

  case "challenge":
    // A rule matched with a soft action. Add friction.
    // Don't issue a session until step-up completes.
    return res.status(200).json({
      requires_challenge: true,
      challenge_type: determineChallengeType(trace),
    });

  case "deny":
    // A rule matched with a hard block.
    return res.status(403).json({ error: "Access denied" });
}

Python

import httpx, os

trace = httpx.post(
    "https://api.tracenow.io/trace",
    headers={"Authorization": f"Bearer {os.environ['TRACENOW_SECRET_KEY']}"},
    json={
        "event": "login",
        "status": "succeeded" if login_succeeded else "failed",
        "subject_user_id": user.id,
        "email": user.email,
        "ip": client_ip,
        "device_token": request.headers.get("x-tn-device-token"),
    },
).json()

match trace["verdict"]:
    case "allow":
        return issue_session(user)
    case "challenge":
        return {"requires_challenge": True}
    case "deny":
        return Response({"error": "Access denied"}, status=403)

Where to go next

Server-side integration

The full /trace request and response contract: every field, getting the client IP, and handling signals_complete.

Rules and policies

Define the conditions that trigger challenge or deny: fields, operators, logic, and ordering.

Getting started

Core concepts

Integration

Use cases

API reference

The three verdicts

allow

challenge

Handling challenge in your app

Challenge types

deny

Edge behavior: what the Worker does

Configuring the deny response at the edge

When a policy is triggered

When no rule matches

Full verdict handling pattern

Where to go next

Server-side integration

Rules and policies

​The three verdicts

​allow

​challenge

​Handling challenge in your app

​Challenge types

​deny

​Edge behavior: what the Worker does

​Configuring the deny response at the edge

​When a policy is triggered

​When no rule matches

​Full verdict handling pattern

​Where to go next

Server-side integration

Rules and policies

The three verdicts

allow

challenge

Handling challenge in your app

Challenge types

deny

Edge behavior: what the Worker does

Configuring the deny response at the edge

When a policy is triggered

When no rule matches

Full verdict handling pattern

Where to go next