This quickstart verifies Trace events in a Node.js backend with @trace-id/sdk-node. The browser sends you an eventId; your server fetches the real event with a secret key and decides what to do.
Before you start
You need a secret key (sk_...) from the dashboard's Keys page, and a frontend that already sends an eventId (see JavaScript, React or Next.js). Node.js 18.17 or later.
- 1
Install the SDK
npm install @trace-id/sdk-nodepnpm add @trace-id/sdk-nodeyarn add @trace-id/sdk-nodebun add @trace-id/sdk-node.envTRACE_SECRET_KEY=sk_... TRACE_ENDPOINT=https://id.example.com - 2
Verify the event
verifyEventcallsGET /v1/events/:eventIdwith your secret key and returns the full event. It works the same in Express, Fastify, NestJS, Hono or a plain handler.TypeScriptimport express from 'express'; import { verifyEvent } from '@trace-id/sdk-node'; import type { VerifyError } from '@trace-id/sdk-node/errors'; const app = express(); app.use(express.json()); app.post('/api/signup', async (req, res) => { const { email, eventId } = req.body; let event = null; try { event = await verifyEvent(eventId, { secretKey: process.env.TRACE_SECRET_KEY!, endpoint: process.env.TRACE_ENDPOINT!, timeoutMs: 1500, }); } catch (err) { console.warn('Trace check skipped', (err as VerifyError).code); // fail open } // decide (next step) });Or use a guard
If you would rather not write the try/catch yourself,
@trace-id/sdk-nodeships guards for the common frameworks. Each reads the event id from thex-trace-event-idheader or the JSON body, verifies it, and exposes the verified event. SetTRACE_SECRET_KEYandTRACE_ENDPOINT, or passsecretKeyandendpoint.import { traceGuard } from '@trace-id/sdk-node/express'; app.post('/api/signup', traceGuard({ reject: (e) => e.suspectScore >= 60 }), (req, res) => { res.json({ visitor: req.trace?.visitorId }); });import { traceHook } from '@trace-id/sdk-node/fastify'; app.post('/api/signup', { preHandler: traceHook({ reject: (e) => e.suspectScore >= 60 }) }, async (req) => { return { visitor: req.trace?.visitorId }; });import { guardRequest } from '@trace-id/sdk-node/web'; const guard = await guardRequest(request, { reject: (e) => e.suspectScore >= 60 }); if (guard.response) return guard.response; // guard.event is the verified eventThe guard answers 400 for a missing or invalid event, 403 when
rejectreturns true, 503 when Trace cannot be reached and 500 for a bad key or missing configuration. PassfailOpen: trueto let requests through (witheventnull) when Trace is unreachable. A wrong key never fails open. Next.js has its own wrapper: see Next.js. - 3
Decide
The event carries a
suspectScorefrom 0 to 100, thereasonsbehind it, and every signal withdetectedanddetails.TypeScriptif (event) { if (event.suspectScore >= 60) return res.status(403).json({ error: 'blocked' }); if (event.signals.multiAccount.detected) return res.status(202).json({ next: 'verify-email' }); if (event.suspectScore >= 25) console.info('review', event.visitorId, event.reasons); } const user = await createUser(email, { traceVisitorId: event?.visitorId }); res.json({ ok: true, id: user.id });Field Use it for visitorIdStable id of this browser. Store it with the account. deviceIdShared by every browser on one device. Use it for bans and multi-accounting. suspectScore0 to 100, the sum of detected signal weights, capped. reasonsWhich signals added how much, for logs and review screens. signalsEvery signal: { detected, details }. See the signal catalog.confidence0 to 1, how sure the match to a returning visitor is. Events can be verified for 60 minutes after they are created. After that
verifyEventthrows with codeexpired.Thresholds are yours
Trace scores; your app decides. The 25 and 60 above are a starting point. Run in shadow mode first (log, do not block) and tune on your own traffic.
- 4
Handle errors
verifyEventthrows aVerifyErrorwhosecodeis one ofinvalid_event_id,timeout,network,unauthorized,not_found,expired,rate_limited,server_errororinvalid_response. For sign-up and login, fail open: continue without the check. For payouts, fail closed. See fail open or fail closed.