All articles Integration

Server-Side Verification With Node.js

The single most common integration mistake in device intelligence is trusting the client. A browser can send any visitor ID, any confidence score, any bot verdict you ask it to, because a determined attacker controls the entire client environment. If your backend reads a fingerprint straight from a request body and acts on it, you have built a check an attacker rewrites in one line. Server-side verification closes that gap.

This guide shows how to verify device results in Node.js properly: obtain a result the client cannot forge, validate its integrity and freshness, and turn it into a risk decision at the moments that matter. The examples use Express, but the pattern applies to any Node framework.

The trust boundary

The client agent collects signals and produces a result. That result must cross to your server in a form the client cannot tamper with. There are two sound patterns.

  • Sealed results. The agent returns an encrypted, integrity-protected blob. Your server holds the decryption key and unseals it locally, with no network round trip. This is the approach behind sealed results.
  • Server-side lookup. The client sends only an opaque request ID. Your server exchanges it for the full result via a trusted API call (GET /v1/events/{requestId} with the secret key), so the fields you act on come from Prynt’s stored copy, not from anything client-controlled JavaScript relayed.

Both share the rule that matters: your decision is based on data the browser could not have edited. What the client sends is at most a reference, never the verdict.

Fetching and validating a result

Here is the shape of a lookup-style verification in Express. The client posts a request ID from the agent, and the server resolves it.

Packages: Prynt’s npm package is coming. Until then, use the plain REST calls below; they work today.

Prynt’s server API is plain HTTPS with your secret key (sk_live_…), so the client is a small helper built on Node’s built-in fetch (Node 18+):

// lib/prynt-server.js: Prynt's server API is plain HTTPS; no package to install.
const PRYNT_API = 'https://api.pryntid.com/v1';

async function pryntApi(method, path, body) {
  const res = await fetch(PRYNT_API + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.PRYNT_SECRET_KEY}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) {
    const err = new Error(`Prynt ${method} ${path} failed: ${res.status}`);
    err.status = res.status;   // 404 = unknown requestId, 401 = bad secret key
    throw err;
  }
  return res.json();
}

export const prynt = {
  getEvent: (requestId) => pryntApi('GET', `/events/${encodeURIComponent(requestId)}`),
};
import express from 'express';
import { prynt } from './lib/prynt-server.js';

const app = express();
app.use(express.json());

async function getVerifiedResult(requestId) {
  // GET https://api.pryntid.com/v1/events/:requestId; throws on failure (err.status 404 = unknown id)
  return prynt.getEvent(requestId);
}

app.post('/login', async (req, res) => {
  const { requestId } = req.body;
  let result;
  try {
    result = await getVerifiedResult(requestId);
  } catch {
    return res.status(400).json({ error: 'unverified_device' });
  }

  // Validate the result before trusting any field
  const fresh = Date.now() - new Date(result.createdAt).getTime() < 60_000;
  const originOk = !!result.url && new URL(result.url).hostname === req.hostname;
  if (!fresh || !originOk) {
    return res.status(400).json({ error: 'stale_or_mismatched' });
  }

  return handleRiskDecision(req, res, result);
});

Three validations are non-negotiable. Freshness rejects a replayed result captured earlier. Origin binding rejects a result generated on a different site and replayed to yours. And the request ID must be treated as single-use for the action it gates, so an attacker cannot reuse one clean result across many login attempts.

Making the risk decision

Once you hold a verified result, the decision logic reads its fields. The point of server-side verification is that these fields are now trustworthy.

function handleRiskDecision(req, res, result) {
  const { visitorId, visitorFound, confidence, smartSignals } = result;
  const reasons = result.risk?.reasons ?? [];

  if (smartSignals.bot?.result || confidence.score < 0.5) {
    return res.status(403).json({ error: 'blocked', reasons });
  }

  if (smartSignals.datacenter?.result || !visitorFound) { // !visitorFound = new device
    return res.status(200).json({ action: 'step_up_mfa', visitorId });
  }

  return res.status(200).json({ action: 'allow', visitorId });
}

Gate on the confidence score so you never act hard on a weak match. Return the reasons to your own logs, not to the client, so you keep an auditable trail without teaching an attacker which signal tripped. This mirrors the language-agnostic advice in Node server-side verification’s siblings for Go and Python device intelligence.

Performance and where to verify

You do not need a fresh verification on every request. Verify at the decision points that carry risk, and cache elsewhere.

SurfaceVerify server-side?
Login and signupYes, every attempt
Payment and checkoutYes, every attempt
Password or email changeYes
Read-only page viewsNo, client signal is enough
Repeated actions in a sessionCache by request ID with a short TTL

For sealed results, unsealing is local and fast, so the cost is negligible. For lookups, cache the resolved result keyed by request ID for the life of the action. Pair the decision with rate limiting by device so a verified-but-abusive device is throttled even when allowed.

Common pitfalls

  • Reading the visitor ID from the request body. If the client sends the ID directly, it is forgeable. Always resolve it from a sealed or looked-up result.
  • Skipping freshness checks. Without a timestamp check, a captured result is replayable indefinitely.
  • Leaking reasons to the client. Reason codes belong in your logs, not the response, or you hand attackers a debugging aid.
  • Failing open silently. If verification errors, decide deliberately whether to allow, step up, or block. Do not default to allow by accident.
  • Verifying everywhere. Over-verifying adds latency without security value. Concentrate it on risk-bearing actions.

The lookup helper above is all a lookup integration needs. For sealed results, unsealing is a few lines of node:crypto; sealed results explained has the function. The integration docs list every event field, and the SDKs page covers other platforms.

Frequently asked questions

Why verify fingerprints server-side instead of trusting the client?

Anything the browser sends can be forged. Server-side verification fetches or decrypts a result the client cannot tamper with, so your risk decision rests on data an attacker cannot rewrite.

Do I need to call an external API on every request?

No. With sealed results you decrypt locally, and with a lookup API you can cache by request ID. Reserve fresh server-side calls for the moments that actually gate a risk decision.

Server-side verification is what separates a decorative fingerprint from a real security control. Move the trust boundary to your backend, validate freshness and origin, gate on confidence, and keep reasons private. Do that, and the visitor ID your risk logic reads is one an attacker cannot simply type into a request.

Try it free

Prynt is device intelligence with a free plan: 5,000 identifications a month, visitor IDs with confidence and bot detection — no credit card. Upgrade to Pro for VPN, proxy, tampering and behavioral signals.

Keep reading