Node.js

Verify events in your Node.js backend with @trace-id/sdk-node.

5 minutes

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. 1

    Install the SDK

    npm install @trace-id/sdk-node
    .env
    TRACE_SECRET_KEY=sk_...
    TRACE_ENDPOINT=https://id.example.com
  2. 2

    Verify the event

    verifyEvent calls GET /v1/events/:eventId with your secret key and returns the full event. It works the same in Express, Fastify, NestJS, Hono or a plain handler.

    TypeScript
    import 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-node ships guards for the common frameworks. Each reads the event id from the x-trace-event-id header or the JSON body, verifies it, and exposes the verified event. Set TRACE_SECRET_KEY and TRACE_ENDPOINT, or pass secretKey and endpoint.

    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 });
    });

    The guard answers 400 for a missing or invalid event, 403 when reject returns true, 503 when Trace cannot be reached and 500 for a bad key or missing configuration. Pass failOpen: true to let requests through (with event null) when Trace is unreachable. A wrong key never fails open. Next.js has its own wrapper: see Next.js.

  3. 3

    Decide

    The event carries a suspectScore from 0 to 100, the reasons behind it, and every signal with detected and details.

    TypeScript
    if (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 });
    FieldUse 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 verifyEvent throws with code expired.

    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. 4

    Handle errors

    verifyEvent throws a VerifyError whose code is one of invalid_event_id, timeout, network, unauthorized, not_found, expired, rate_limited, server_error or invalid_response. For sign-up and login, fail open: continue without the check. For payouts, fail closed. See fail open or fail closed.

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.