Documentation · Prynt Control

Friction ladder

Instead of only blocking, each Control decision says which step to ask for: none, a captcha, email verification, a card or a passkey, or block. With code for Cloudflare Turnstile, email codes and WebAuthn passkeys.

Most suspicious requests do not deserve a block. A person on a VPN, a second trial from a shared office computer, a login from a new phone: each is worth one small check, not a closed door. The friction ladder is the order in which Control suggests those checks, from the lightest to the heaviest:

RungstepWhen Control suggests itWhat it costs a good user
0noneNothing unusualNothing
1captchaSigns of automation, many logins or checkouts from one device in a short timeA few seconds, often invisible
2verify_emailA device that already started a trial or holds other accounts, a disposable email, Tor, a VPN on a trial or bonus, a browser altering its fingerprint (privacy extensions do too), a new device for a loginOpening their inbox
3card_or_passkeyStrong repeat evidence (several trials, or a bonus already claimed on the device), fraud reported elsewhere, a country change within an hour on a loginA card form or a fingerprint/face prompt
4blockDirect evidence: a device or account labeled fraud, your deny list, a device that keeps claiming the same bonus, card testingThe whole session

Control returns the lowest rung it believes settles the doubt; your code shows it. The full list of reasons and the rung each one leads to is in use-case decisions. There is no SMS rung: phone numbers are cheap for fraudsters to rent and costly for good users, so Control never asks for one.

The idea is documented by large platforms. Airbnb describes applying “targeted friction” to risky cases instead of blocking them (Airbnb Engineering, 2018), and Google measured that device-based login challenges stopped 100% of automated hijacking attempts and over 94% of phishing-rooted ones in its data (Doerfler et al., WWW 2019). Those are their results on their traffic, not a promise for yours; the lesson that transfers is that the kind of step matters, and that every step costs real users something.

Route the step

// After reading event.control on your server (see use-case decisions)
switch (event.control.step) {
  case 'none':            return proceed();
  case 'captcha':         return res.json({ next: 'captcha' });
  case 'verify_email':    await sendEmailCode(user); return res.json({ next: 'verify_email' });
  case 'card_or_passkey': return res.json({ next: user.hasPasskey ? 'passkey' : 'card' });
  case 'block':           return res.status(403).json({ error: 'unavailable' });
}

When the user passes or fails a step, tell Prynt from your server. The examples below call this helper:

async function reportStep(requestId, step, passed) {
  await fetch('https://api.pryntid.com/v1/control/steps', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.PRYNT_SECRET_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ requestId, step, passed }),   // step: "captcha" | "verify_email" | "card_or_passkey"
  });
}

requestId is the identification that asked for the step. step is captcha, verify_email or card_or_passkey (email, card and passkey are accepted as aliases), and passed is true or false. Report an abandoned step as passed: false. The answer is 201:

{ "requestId": "req_…", "visitorId": "vst_…", "useCase": "free_trial", "step": "captcha", "passed": true,
  "createdAt": "2026-12-03T14:05:11Z", "recorded": true }

Errors: 422 for a missing requestId, an unknown step or a passed that is not a boolean; 403 plan_required outside Control; 404 for a requestId your account does not have.

What a step result changes:

  • A passed step vouches for the device for 30 days: the next decision for the same use case answers allow (reason STEP_PASSED), unless the evidence now calls for a higher step than the one passed, or is direct.
  • A failed or abandoned step in the last 7 days moves the next answer one rung up (reason STEP_FAILED), up to card_or_passkey.

A step result is not a fraud label. To label a device or account fraud or legit, use POST /v1/outcomes or the console.

Rung 1 — captcha with Cloudflare Turnstile

Any captcha works; Turnstile is a good default because most real users never see a puzzle. Render the widget only when Control asks for it:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<form id="signup" method="post" action="/signup/step">
  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
  <button type="submit">Continue</button>
</form>

The widget adds a cf-turnstile-response field to the form. Verify it on your server, never in the browser:

async function verifyTurnstile(token, ip) {
  const r = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
    method: 'POST',
    body: new URLSearchParams({ secret: process.env.TURNSTILE_SECRET, response: token, remoteip: ip }),
  });
  const out = await r.json();
  return out.success === true;
}

app.post('/signup/step', async (req, res) => {
  const passed = await verifyTurnstile(req.body['cf-turnstile-response'], req.ip);
  await reportStep(req.session.requestId, 'captcha', passed);
  if (!passed) return res.status(400).json({ error: 'captcha_failed' });
  return proceed();
});

Rung 2 — verify the email

A short code to the address the user typed proves they control it, and makes every extra account cost one real inbox.

import crypto from 'node:crypto';

async function sendEmailCode(user) {
  const code = String(crypto.randomInt(0, 1_000_000)).padStart(6, '0');
  const hash = crypto.createHash('sha256').update(code + user.id).digest('hex');
  await db.emailCodes.upsert({ userId: user.id, hash, expiresAt: Date.now() + 10 * 60_000, attempts: 0 });
  await mailer.send({ to: user.email, subject: 'Your code', text: `Your code is ${code}. It expires in 10 minutes.` });
}

async function checkEmailCode(user, code) {
  const row = await db.emailCodes.get(user.id);
  if (!row || row.expiresAt < Date.now() || row.attempts >= 5) return false;
  await db.emailCodes.update(user.id, { attempts: row.attempts + 1 });
  const hash = crypto.createHash('sha256').update(String(code) + user.id).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(row.hash));
}

Keep it a code or a link to the email they gave; do not swap it for a phone number.

Rung 3a — a passkey (WebAuthn)

For logins and for returning users, a passkey is the strongest light step: it is bound to the device and the site, so a phisher cannot replay it. This example uses SimpleWebAuthn (v11 or later).

Server, issue the challenge:

import { generateAuthenticationOptions, verifyAuthenticationResponse } from '@simplewebauthn/server';

app.post('/passkey/options', async (req, res) => {
  const creds = await db.passkeys.forUser(req.user.id);
  const options = await generateAuthenticationOptions({
    rpID: 'example.com',
    allowCredentials: creds.map((c) => ({ id: c.id, transports: c.transports })),
    userVerification: 'preferred',
  });
  req.session.challenge = options.challenge;
  res.json(options);
});

Browser, ask the user:

import { startAuthentication } from '@simplewebauthn/browser';

const optionsJSON = await fetch('/passkey/options', { method: 'POST' }).then((r) => r.json());
const assertion = await startAuthentication({ optionsJSON });
await fetch('/passkey/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(assertion) });

Server, verify it:

app.post('/passkey/verify', async (req, res) => {
  const cred = await db.passkeys.get(req.body.id);
  const { verified, authenticationInfo } = await verifyAuthenticationResponse({
    response: req.body,
    expectedChallenge: req.session.challenge,
    expectedOrigin: 'https://example.com',
    expectedRPID: 'example.com',
    credential: { id: cred.id, publicKey: cred.publicKey, counter: cred.counter },
  });
  if (verified) await db.passkeys.setCounter(cred.id, authenticationInfo.newCounter);
  await reportStep(req.session.requestId, 'card_or_passkey', verified);
  res.json({ ok: verified });
});

Rung 3b — a card, without charging it

For a trial or a bonus, asking for a card makes each extra account cost a real payment method. With Stripe, a SetupIntent saves and verifies the card without charging it:

const intent = await stripe.setupIntents.create({ customer: customer.id, usage: 'off_session' });
res.json({ clientSecret: intent.client_secret });   // confirm it in the browser with Stripe Elements

When the card is confirmed, report the step with reportStep(requestId, 'card_or_passkey', true). The Stripe connection, which will turn later disputes on that card into fraud labels, is still rolling out in Prynt Control.

Choosing your strongest rung

In the console, Decisions (Control section of the sidebar) sets, per use case, the highest step you are willing to ask for (maxStep). A product that never asks for a card can cap free trials at verify_email; Control then returns block only when the evidence is direct, and verify_email, with cappedAt: "verify_email", in the cases where it would otherwise have suggested a card. The same setting is available through PUT /admin/control/settings (see use-case decisions).

Start in mirror mode: every answer is allow, the step Control would have asked for is kept in control.wouldBe, and Decisions counts how many requests would have been stepped up or blocked, and why, before anyone sees a step.