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
Install the SDK
npm install @trace-id/sdk-nodepnpm add @trace-id/sdk-nodeyarn add @trace-id/sdk-node.envTRACE_SECRET_KEY=sk_... TRACE_ENDPOINT=https://id.example.com - 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-idheader. On success it setsreq.traceto the server-verified event.TypeScriptimport 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
rejectsays so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration.failOpen: truelets requests through (with the eventnull) when Trace is unreachable. A wrong key never fails open.For TypeScript, tell Express about
req.trace:TypeScriptimport type { EventResponse } from '@trace-id/signals/api'; declare global { namespace Express { interface Request { trace?: EventResponse | null; } } } - 3
Decide yourself instead
If you want full control, call
verifyEventin the handler and decide there. See the Node.js guide.Start in shadow mode
For the first week, log
event.suspectScoreandevent.reasonsinstead of rejecting. Look at who would have been blocked, then pick thresholds you trust.