Integration guides
Express / Node integration
Protect an Express route and publish transaction evidence to the control plane.
Prerequisites
- A TxnShield organization, project, and environment.
- One publishable key and one secret key from the same environment.
- An Express app with authenticated user context available on the request.
Install and configure
Use the package manager your application already uses. Package names are pre-launch TxnShield npm names and should match the SDK packages in this monorepo.
bash
npm install @txnshield/sdk-node
pnpm add @txnshield/sdk-node
yarn add @txnshield/sdk-node
bun add @txnshield/sdk-nodeProtect a route
ts
import express from "express";
import { createTxnShieldNode } from "@txnshield/sdk-node";
const app = express();
const txnshield = createTxnShieldNode({
secretKey: process.env.TXNSHIELD_SECRET_KEY!,
apiBaseUrl: process.env.TXNSHIELD_API_BASE_URL!,
});
app.post("/customers/:id/export", async (req, res, next) => {
const decision = await txnshield.evaluate({
operationKey: "invoice.export",
actor: { id: req.user.id, roles: req.user.roles },
resource: { type: "customer", id: req.params.id },
requestData: { requestedCount: Number(req.body.count ?? 1) },
});
if (decision.decision === "deny") {
return res.status(403).json({ error: "Transaction denied" });
}
if (decision.decision === "step_up_required") {
return res.status(409).json({ challenge: "step_up_required" });
}
return next();
});How to test
Call the route with a real authenticated user. Then open the environment Event Stream and confirm the operation key, actor, resource, decision, and score appear.
Common mistakes
- Evaluating before authentication middleware has populated req.user.
- Using request bodies that contain raw secrets or unnecessary PII.
- Ignoring step_up_required and continuing the handler anyway.
Next steps