Node.js (Backend/API)

This tutorial demonstrates how to add auth to a Node application using BlitzWare.

Lightweight Node.js SDK for BlitzWare resource servers (APIs).

This package provides simple middleware for Express and Koa to validate incoming bearer tokens. It prefers token introspection (avoids shipping a shared signing secret) and also supports the common pattern of mounting a non-enforcing parser once and enforcing auth on a per-route basis.

This tutorial is based on the example app.

1. Configure BlitzWare

2. Install the BlitzWare Node API SDK

3. Configure environment

4. Express setup

5. Koa setup

6. How it works

1) Configure BlitzWare

Get Your Application Keys

You will need some details about your application to communicate with BlitzWare. You can get these details from the Application Settings section in the BlitzWare dashboard.

You need the Client ID and Client Secret (given when app was created).

Configure Redirect URIs

A redirect URI is a URL in your application where BlitzWare redirects the user after they have authenticated. The redirect URI for your app must be added to the Redirect URIs list in your Application Settings under the Security tab. If this is not set, users will be unable to log in to the application and will get an error.

2) Install the BlitzWare Node API SDK

Run the following command within your project directory to install the BlitzWare Node API SDK:

npm

npm install blitzware-node-api-sdk

yarn

yarn add blitzware-node-api-sdk

3) Configure environment

Create a .env file:

BLITZWARE_CLIENT_ID=your-client-id
BLITZWARE_CLIENT_SECRET=your-client-secret

4) Express setup

const express = require("express");
require("dotenv").config();
const { expressAuth, expressRequireAuth } = require("blitzware-node-api-sdk");

const app = express();
app.use(express.json());

app.use(
  expressAuth({
    clientId: process.env.BLITZWARE_CLIENT_ID,
    clientSecret: process.env.BLITZWARE_CLIENT_SECRET,
  })
);

app.get("/public", (req, res) => res.json({ ok: true, public: true }));

app.get("/protected", expressRequireAuth(), (req, res) => {
  res.json({ ok: true, user: req.auth && req.auth.payload });
});

const port = process.env.PORT;
app.listen(port, () =>
  console.log(`Express API example listening on http://localhost:${port}`)
);

5) Koa setup

const Koa = require("koa");
const Router = require("@koa/router");
const bodyParser = require("koa-bodyparser");
require("dotenv").config();
const { koaAuth, koaRequireAuth } = require("blitzware-node-api-sdk");

const app = new Koa();
const router = new Router();
app.use(bodyParser());

app.use(
  koaAuth({
    clientId: process.env.BLITZWARE_CLIENT_ID,
    clientSecret: process.env.BLITZWARE_CLIENT_SECRET,
  })
);

router.get("/public", (ctx) => {
  ctx.body = { ok: true, public: true };
});

router.get("/protected", koaRequireAuth(), (ctx) => {
  ctx.body = { ok: true, user: ctx.state.auth && ctx.state.auth.payload };
});

app.use(router.routes()).use(router.allowedMethods());

const port = process.env.PORT;
app.listen(port, () =>
  console.log(`Koa API example listening on http://localhost:${port}`)
);

6) How it works

What this package exports

• expressAuth(options) -> returns an Express parser middleware. Mount with app.use(expressAuth(...)).

• expressRequireAuth() -> returns an Express per-route enforcer middleware.

• koaAuth(options) -> returns a Koa parser middleware. Mount with app.use(koaAuth(...)).

• koaRequireAuth() -> returns a Koa per-route enforcer middleware.

These helpers are implemented in src/middleware.ts and re-exported from src/index.ts (the package entry).

Quick concepts and recommended pattern

• Parser (non-enforcing): the middleware returned by expressAuth() / koaAuth() tries to parse and introspect a bearer token on every request and will attach the result to req.auth (Express) or ctx.state.auth (Koa) when a valid token is present. The parser does not block anonymous requests.

• Require (per-route): the middleware returned by expressRequireAuth() / koaRequireAuth() enforces authentication for a specific route. If req.auth/ctx.state.auth is missing, it will perform on-demand introspection using the options previously provided via expressAuth()/koaAuth() (the helpers store the config internally) and reject the request if the token is invalid or missing.

Recommended usage for multi-file projects:

1. In your main entrypoint mount the parser once so it runs on every request:

// app.js
require("dotenv").config();
const express = require("express");
const { expressAuth } = require("blitzware-node-api-sdk");

const app = express();
app.use(express.json());

// mount parser globally (non-enforcing)
app.use(
  expressAuth({
    clientId: process.env.BLITZWARE_CLIENT_ID,
    clientSecret: process.env.BLITZWARE_CLIENT_SECRET,
  })
);

app.get("/public", (req, res) => res.json({ ok: true }));

// mount routers or individual route files after this
app.use("/users", require("./routes/users"));

app.listen(process.env.PORT || 3000);

1. In each route file, use the per-route enforcer where you need protection:

// routes/users.js
const express = require("express");
const router = express.Router();
const { expressRequireAuth } = require("blitzware-node-api-sdk");

router.get("/", (req, res) => res.json({ ok: true, users: [] })); // public

router.get("/me", expressRequireAuth(), (req, res) => {
  // parse middleware attached req.auth earlier if token present
  res.json({ ok: true, me: req.auth && req.auth.payload });
});

module.exports = router;

This pattern avoids re-creating auth middleware in every route file while ensuring per-route enforcement works.