How do you secure a Node.js/Express API?

How do you secure a Node.js/Express API?

Protect the request in the handler before business logic runs. Authentication, object-level authorization, and input validation stay in your code. Arcjet adds three request-path controls you can compose on the same protect() call: Shield for common web attacks, detectBot for automated clients, and a rate limit for abuse.

This guide assumes you already have an Express app. @arcjet/node declares >=22.21.0 <23 || >=24.5.0, so use Node.js 24 (Active LTS) or Node.js 22.21.0 or later; Node.js 20 went end-of-life in April 2026 and Node.js 23 is not supported. You also need Express 4 or 5 and an Arcjet site key in ARCJET_KEY. ESM ("type": "module") is required rather than recommended, because the package is ESM-only and cannot be required. TypeScript is optional. Skip scaffolding if the app already compiles and starts.

For more information about the broader API baseline, see API security best practices. For more information about algorithm choice, see rate limiting algorithms.

What do you install?

Pin the Node adapter at v1:

1
npm install @arcjet/node@1.10.0 express

Create a .env.local file in the project root. Set ARCJET_ENV=development when Node does not already set NODE_ENV, and paste the site key from the Arcjet dashboard:

1
ARCJET_ENV=development
2
ARCJET_KEY=ajkey_your_site_key

Never commit the key. In development, start Node with --env-file .env.local. In production, inject ARCJET_KEY from the host secret store.

Which Arcjet rules belong on an Express API?

The following table lists the three rules you usually combine on a public API. Each answers a different question, so one rule does not replace another.

mode is "LIVE" (enforce) or "DRY_RUN" (log only). Start new rules in dry run on a busy route, then switch to live one rule at a time.

detectBot takes exactly one of allow or deny. An allow list denies every detected bot that is not named. A deny list allows every detected bot that is not named. allow: [] is valid and blocks every detected bot. Do not use the older block: ["AUTOMATED"] option; it is not part of the v1 API.

Pass allow: ["CATEGORY:SEARCH_ENGINE"] on public content that search engines should index. Pass a deny list when you only want to block a few abusive families and leave other automation through. For more information about allow lists, verification, and spoofed user agents, see bot detection techniques.

How do you call protect() in Express middleware?

Create one client at module scope. Call protect() once per request, before the route handler. The following example uses Shield, an empty bot allow list, and a tight fixed window so you can see a deny without generating load.

1
import arcjet, { detectBot, fixedWindow, shield } from "@arcjet/node";
2
import express from "express";
3

4
const app = express();
5

6
const aj = arcjet({
7
  key: process.env.ARCJET_KEY!,
8
  rules: [
9
    shield({ mode: "LIVE" }),
10
    detectBot({
11
      mode: "LIVE",
12
      allow: [],
13
    }),
14
    // Demo-only: one request per minute per default characteristic (IP).
15
    // Do not ship this limit. Use a production window and max, or tokenBucket.
16
    fixedWindow({
17
      mode: "LIVE",
18
      window: "1m",
19
      max: 1,
20
    }),
21
  ],
22
});
23

24
app.use(async (req, res, next) => {
25
  const decision = await aj.protect(req);
26

27
  if (decision.isErrored()) {
28
    // Default fail-open: log and continue. Fail closed on sensitive routes.
29
    console.error("Arcjet error", decision.reason.message);
30
  }
31

32
  if (decision.isDenied()) {
33
    if (decision.reason.isRateLimit()) {
34
      return res.status(429).json({ error: "Too Many Requests" });
35
    }
36
    if (decision.reason.isBot()) {
37
      return res.status(403).json({ error: "Forbidden" });
38
    }
39
    if (decision.reason.isShield()) {
40
      return res.status(403).json({ error: "Forbidden" });
41
    }
42
    return res.status(403).json({ error: "Forbidden" });
43
  }
44

45
  return next();
46
});
47

48
app.get("/", (_req, res) => {
49
  res.status(200).json({ message: "Hello World" });
50
});
51

52
app.listen(3000);

fixedWindow({ window: "1m", max: 1 }) is a demonstration so a second request in the same minute returns 429. A production API needs a limit that matches the resource: for example window: "1h" and max: 1000, or a sliding window of 100 requests per 60 seconds. A login or password-reset route should use a much smaller max than a public catalog.

The default characteristic is ip.src. Shared NATs collapse many users onto one key, and an attacker who rotates addresses resets the counter. After authentication, set characteristics: ["userId"] on the rule and pass { userId } to protect().

How do you handle each denial reason?

decision.isDenied() is the high-level verdict. Branch on decision.reason so clients get the correct status and you can tune one rule without guessing.

• isRateLimit(): return HTTP 429. Include Retry-After when you have decision.reason.reset (seconds until the window refills). A 429 without a retry hint turns a well-behaved client into a hot loop.
• isBot(): return HTTP 403. The client matched a detected bot that your allow or deny list does not permit. Inspect decision.reason for the identified bots and categories.
• isShield(): return HTTP 403. Shield scored the request as a common web attack. Do not echo the matched payload back to the client.
• isErrored(): a rule could not finish (timeout, misconfiguration, or transport). Arcjet fails open by default so an outage does not take the API down. Log decision.reason.message. Fail closed only on routes where an unknown verdict is worse than downtime.

Look up decision.id in the Arcjet dashboard when you need the full request record. Local decisions use an lreq_ prefix; cloud decisions use req_.

How do you choose a production rate limit?

Replace the demo max: 1 before you deploy. Pick the algorithm from the cost of the route, not from a global default.

• Fixed window is simple and bursts at the reset. Use it for coarse internal quotas.
• Sliding window is the usual public-API default when you want "no more than n in the last interval."
• Token bucket is the right model when request cost varies. Configure refillRate, interval (seconds as a number, or a duration string such as "60s"), and capacity. Pass { requested } to protect() so a cheap read costs 1 token and an export costs more.

The following token-bucket rule allows a burst of 20, then 10 tokens every 60 seconds, keyed on the authenticated user:

1
import arcjet, { tokenBucket } from "@arcjet/node";
2

3
const aj = arcjet({
4
  key: process.env.ARCJET_KEY!,
5
  rules: [
6
    tokenBucket({
7
      mode: "LIVE",
8
      characteristics: ["userId"],
9
      refillRate: 10,
10
      interval: 60,
11
      capacity: 20,
12
    }),
13
  ],
14
});
15

16
app.use(async (req, res, next) => {
17
  const userId = req.user?.id;
18
  if (!userId) {
19
    return res.status(401).json({ error: "Unauthorized" });
20
  }
21

22
  const decision = await aj.protect(req, { userId, requested: 1 });
23
  if (decision.isDenied() && decision.reason.isRateLimit()) {
24
    return res.status(429).json({ error: "Too Many Requests" });
25
  }
26
  return next();
27
});

For more information about burst behavior, identifiers, and 429 responses, see rate limiting algorithms.

How do you run and verify the rules?

Start the process with the env file loaded, for example node --env-file .env.local --import tsx src/app.ts or your existing TypeScript runner. A first GET / should return 200 and {"message":"Hello World"}. A second request inside the demo window should return 429. A curl request against allow: [] should return 403 because curl is a detected tool.

When you are ready for real traffic, raise max, switch the bot rule to the allow or deny list that matches the route, and keep Shield in live mode. Compile TypeScript to dist/ and start the compiled file in production; the Arcjet client is the same in both environments.