Device risk

A visitor ID for every browser on your sign-in, sign-up, password-reset and approval pages, like Fingerprint's visitorId, and the risk engine's view of it. The page identifies with your public site key and gets { visitorId, requestId, confidence }; your server reads the trusted result by requestId and passes it to sign-ins. A paid add-on, off until you turn it on (Device risk in the dashboard).

The script tag (script.js, with your site key and its version's integrity hash from Device risk → Settings; a page that loads …/device.js, its first name, keeps working with the same hash) identifies the browser when the page loads and puts the requestId into a hidden touchque_request_id field of every form, forms added later too; it takes a new one after 10 minutes and after each submit. On submit it adds how the pointer and the fingers moved, after the requestId and a dot: 18 characters of counts the browser computed (presses on a jumped pointer and how long they lasted, how straight long strokes and swipes were, how long taps lasted), never a position or a path; data-pointer="off" leaves it out. Your server passes that field to deviceRisk.check as it came. Single-page apps read window.TouchqueDevice (ready, value(), requestId, refresh()); the 1.6.0 tag set window.TouchQueDevice.

<script src="https://cdn.touchque.com/device/v2.0.0/script.js" data-site-key="tqpk_…" data-purpose="sign_in"
        integrity="sha384-a69uLWQn3eccd/RGOZIKDLN16dOQIXvX2eGDlOUYpmMMq4QVyqiTcuoRgT17JGLG" crossorigin="anonymous" async></script>

The page reads coarse traits (OS, browser family and major version, time zone, languages, screen size, cores, memory class, touch points, the graphics card's name), short hashes of how the browser draws a test text, plays a test sound, which of 25 common fonts it has, a few Math results and its WebGL limits, and findings (replaced browser functions, a virtual machine, a headless browser, a private window where detectable). Touchque keeps no raw trait: keyed hashes with a key of your workspace alone, coarse labels, the account, the country and a keyed hash of the address's network, for 30 to 90 days as you set; the address itself for a day at most. Never a MAC address, a serial number or a cross-customer device graph.

Ad blockers and browser privacy lists drop scripts and calls to known third-party fingerprinting hosts, honest visitors' too (they then get Identification missing, a step-up at most). Large sites serve the tag and its identify call from their own domain instead, like Fingerprint's proxy integrations: GET /_tq/device/vX.Y.Z/script.js goes to https://cdn.touchque.com/device/vX.Y.Z/script.js (the same bytes, so the same integrity hash) and POST /_tq/device-risk/identify to https://api.touchque.com/device-risk/identify. The tag then points at your domain, and your Content-Security-Policy needs only 'self':

<script src="https://www.example.com/_tq/device/v2.0.0/script.js" data-site-key="tqpk_…" data-purpose="sign_in" data-api="https://www.example.com/_tq"
        integrity="sha384-a69uLWQn3eccd/RGOZIKDLN16dOQIXvX2eGDlOUYpmMMq4QVyqiTcuoRgT17JGLG" crossorigin="anonymous" async></script>

The proxy secret: behind your proxy every visitor reaches Touchque from your proxy's address. Send the visitor's address as X-Touchque-Client-IP with your workspace's proxy secret as X-Touchque-Proxy-Secret (tqps_…, Device risk → Settings for owners and admins; GET /device-risk/settings with the API key). Touchque then records and scores the visitor's address and counts the per-address limit (60 identifications a minute) on it, not on your proxy. Keep the secret on the server like the API key, never in a page or in git. A wrong one is 403 proxy_secret_invalid; replacing the site key replaces it. Without it the proxy still works, but every visitor counts against the proxy's one address: small sites only. Drop your own cookies on the way, pass Origin on as it came (Touchque checks it against your domains and origins), and pass the visitor's address as clientIp to deviceRisk.check on your server.

location /_tq/device/ {
    proxy_pass https://cdn.touchque.com/device/;
    proxy_ssl_server_name on;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
}
location = /_tq/device-risk/identify {
    limit_except POST { deny all; }
    proxy_pass https://api.touchque.com/device-risk/identify;
    proxy_ssl_server_name on;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_set_header X-Forwarded-For "";
    proxy_set_header X-Touchque-Proxy-Secret "tqps_…";   # Device risk → Settings; keep this file out of git
    proxy_set_header X-Touchque-Client-IP $remote_addr;  # behind a load balancer: set_real_ip_from + real_ip_header first
}

// Route: www.example.com/_tq/*   Secret: wrangler secret put TOUCHQUE_PROXY_SECRET
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (request.method === 'GET' && url.pathname.startsWith('/_tq/device/')) {
      return fetch('https://cdn.touchque.com/device/' + url.pathname.slice('/_tq/device/'.length));
    }
    if (request.method === 'POST' && url.pathname === '/_tq/device-risk/identify') {
      return fetch('https://api.touchque.com/device-risk/identify', {
        method: 'POST',
        headers: {
          'Content-Type': 'text/plain',
          Origin: request.headers.get('Origin') || '',
          'X-Touchque-Proxy-Secret': env.TOUCHQUE_PROXY_SECRET,
          'X-Touchque-Client-IP': request.headers.get('CF-Connecting-IP') || '',
        },
        body: await request.text(),
      });
    }
    return new Response('Not found', { status: 404 });
  },
};

// middleware.ts (Next.js 16: proxy.ts, export function proxy). TOUCHQUE_PROXY_SECRET in the environment.
import { NextRequest, NextResponse } from 'next/server';

export const config = { matcher: '/_tq/:path*' };

export async function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  if (req.method === 'GET' && pathname.startsWith('/_tq/device/')) {
    return NextResponse.rewrite(new URL('https://cdn.touchque.com/device/' + pathname.slice('/_tq/device/'.length)));
  }
  if (req.method === 'POST' && pathname === '/_tq/device-risk/identify') {
    const r = await fetch('https://api.touchque.com/device-risk/identify', {
      method: 'POST',
      headers: {
        'Content-Type': 'text/plain',
        Origin: req.headers.get('origin') ?? '',
        'X-Touchque-Proxy-Secret': ({}).TOUCHQUE_PROXY_SECRET ?? '',
        // On Vercel the first x-forwarded-for entry is the visitor; behind your own load balancer, its header.
        'X-Touchque-Client-IP': (req.headers.get('x-forwarded-for') ?? '').split(',')[0].trim(),
      },
      body: await req.text(),
    });
    return new Response(r.body, { status: r.status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } });
  }
  return new Response('Not found', { status: 404 });
}

{
  "rewrites": [
    { "source": "/_tq/device/:path*", "destination": "https://cdn.touchque.com/device/:path*" },
    { "source": "/_tq/device-risk/identify", "destination": "https://api.touchque.com/device-risk/identify" }
  ]
}

Limits: a visitor's address gets 60 identifications a minute; a site key, and a workspace's calls to deviceRisk.check, get 1,200 a minute each. Above a limit the call answers 429 with Retry-After. Device risk → Settings shows your number (ratePerMinute in GET /device-risk/settings); a bigger site asks support (support@touchque.com) with its expected traffic and Touchque raises it for the workspace.

Vercel rewrites cannot add the proxy secret: use them for small sites, or the Next.js middleware (also on Vercel) for the identify path at volume. With a verified Touchque Login custom domain there is nothing to proxy: Touchque serves both paths on it, and Device risk → Settings shows the tag with data-api="https://login.example.com/_tq".

A busy site has millions of identifications, so nothing lists them all: GET /device-risk/events (deviceRisk.searchEvents in every SDK, the Identifications tab in the dashboard) answers one page, newest first, for a date range of at most 90 days within your retention (7 by default), filtered by signal, stepUp, page (kind), origin, ip (an address or a CIDR range like 203.0.113.0/24; never returned), account, visitorId or requestId, each on an index. Pass nextCursor back as cursor until it is null (1 to 100 a page); do not page by moving from/to. A search that would read too much answers 422 search_too_broad: narrow the range or add a filter. For everything at once: a data request (Organization → Data requests, JSON or CSV, one row per identification, no address), the webhooks and the log stream.

Device risk → Overview shows the last 30 days, 90 days or 12 months per day (identifications with the step-ups, signals with the enforced part; from daily counts kept 400 days, longer than the identifications themselves) and the recent identifications, updated every 10 seconds while the page is open. Alerts (Device risk → Settings → Alerts) tell your people when something is going on; each rule has an on/off and a threshold and alerts at most once an hour. They go to your webhook and by email to your organization's owners and admins (once a mail sender is set up). An alert never changes a sign-in: the risk engine decides those.

Your webhook (Developers → Webhooks) gets DEVICE_RISK_SIGNAL when an identification or a check raises a signal that asks for more (enforced or in shadow; page loads of the same visitor with the same signals once in 10 minutes, every check), and DEVICE_RISK_ALERT when an alert goes off. Signed like every event. They carry the requestId, visitorId, page, account when known, confidence, signals and the engine's verdict with its case code; never a trait. For an SSO organization with a log stream (Splunk, Datadog, Sentinel, webhook, S3), the same events also go to that stream, category device_risk.