ZTLayer Logo
Start Building

Express Integration Guide

The @ztlayer/node SDK includes built-in, highly optimized Express middleware. It allows you to protect your entire application globally or secure specific, sensitive routes (like login endpoints) with a single line of code.

1. Installation

Install the official Node package:

npm install @ztlayer/node

2. Configuration & Initialization

Set your API key in your .env file.

ZTLAYER_API_KEY="zt_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Initialize the ZTLayer instance once during your application boot process.

import express from 'express';
import { ZTLayer } from '@ztlayer/node';
 
const app = express();
 
const security = new ZTLayer({
  apiKey: process.env.ZTLAYER_API_KEY,
  environment: process.env.NODE_ENV,
  failMode: 'open' // Recommended for production uptime
});

3. Global Middleware (Recommended)

To protect your entire API from OWASP Top 10 vulnerabilities (SQLi, XSS) and malicious bots, attach the middleware globally before your route definitions.

// Add basic body parsers first if needed
app.use(express.json());
 
// 1. Attach ZTLayer globally
app.use(security.expressMiddleware());
 
// 2. Define your routes
app.get('/api/users', (req, res) => {
  res.json({ message: "You are secure." });
});
 
// 3. Standard Express Error Handler
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});
 
app.listen(3000, () => console.log('Secure Express server running'));

How the Middleware works

The security.expressMiddleware() function intercepts the request, sends the IP, Headers, and URI to the ZTLayer Edge, and awaits a verdict.

  • If safe (Allow), it calls next().
  • If malicious (Block), it terminates the request, sets the HTTP status to 403, and responds with a standard JSON error message. Your downstream routes are never executed.

4. Route-Specific Protection

If you have a high-traffic public API where edge latency is unacceptable for every single request, or you only want to protect specific sensitive endpoints (like Authentication), you can apply the middleware on a per-route basis.

const app = express();
 
// A highly sensitive endpoint (e.g., Login, Payment)
// Applying strict behavioral analysis and credential stuffing protection
app.post(
  '/api/auth/login', 
  express.json(), 
  security.expressMiddleware({ strict: true }), 
  (req, res) => {
    // Only executes if ZTLayer verifies the request is safe
    authenticateUser(req.body);
    res.status(200).send('Authenticated');
  }
);
 
// A public, read-only endpoint bypassed by ZTLayer
app.get('/api/public-data', (req, res) => {
  res.json({ data: "Public content" });
});

5. Trusting Proxies (Critical for Heroku/AWS ALB)

If your Express application sits behind a reverse proxy, load balancer, or CDN (like Heroku, AWS Application Load Balancer, or Cloudflare), Express will incorrectly report the proxy's IP address instead of the client's actual IP.

You must configure Express to trust the proxy, otherwise ZTLayer will block the proxy IP, taking your entire application offline.

const app = express();
 
// Trust the first proxy in the X-Forwarded-For chain
app.set('trust proxy', 1);
 
// Now initialize ZTLayer
app.use(security.expressMiddleware());

Next Steps