Express

Guard Express routes with the traceGuard middleware.

5 minutes

This quickstart verifies Trace events in an Express app with the traceGuard middleware from @trace-id/sdk-node.

Before you start

You need a secret key (sk_...) from the dashboard's Keys page and a frontend that sends an eventId (see the Web quickstarts). Send it in the x-trace-event-id header or as eventId in the request body.

  1. 1

    Install the SDK

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

    Guard a route

    Mount the guard after your body parsers so it can read the event id from the parsed body. It also reads the x-trace-event-id header. On success it sets req.trace to the server-verified event.

    TypeScript
    import express from 'express';
    import { traceGuard } from '@trace-id/sdk-node/express';
    
    const app = express();
    app.use(express.json());
    app.use(express.urlencoded({ extended: false })); // for plain HTML forms
    
    app.post(
      '/api/signup',
      traceGuard({ failOpen: true, reject: (event) => event.suspectScore >= 60 }),
      (req, res) => {
        const event = req.trace; // null only with failOpen when Trace was unreachable
        // create the account, and store event?.visitorId with it for later lookups
        res.json({ ok: true });
      },
    );

    The guard answers 400 for a missing or invalid event, 403 when reject says so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration. failOpen: true lets requests through (with the event null) when Trace is unreachable. A wrong key never fails open.

    For TypeScript, tell Express about req.trace:

    TypeScript
    import type { EventResponse } from '@trace-id/signals/api';
    
    declare global {
      namespace Express {
        interface Request {
          trace?: EventResponse | null;
        }
      }
    }
  3. 3

    Decide yourself instead

    If you want full control, call verifyEvent in the handler and decide there. See the Node.js guide.

    Start in shadow mode

    For the first week, log event.suspectScore and event.reasons instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.

Frontends

Next steps

Suggest an edit

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