# Node.js (Backend/API)

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.

{% hint style="info" %}
This tutorial is based on the [example app](https://github.com/LanderDK/blitzware-node-api-sdk/tree/master/examples).
{% endhint %}

1. [**Configure BlitzWare**](#configure-blitzware)
2. [**Install the BlitzWare Node API SDK**](#id-2-install-the-blitzware-node-api-sdk)
3. [**Configure environment**](#id-3-configure-environment)
4. [**Express setup**](#id-4-express-setup)
5. [**Koa setup**](#id-5-koa-setup)
6. [**How it works**](#id-6-how-it-works)

## 1) Configure BlitzWare <a href="#configure-blitzware" id="configure-blitzware"></a>

### Get Your Application Keys <a href="#get-your-application-keys" id="get-your-application-keys"></a>

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.

<figure><img src="/files/2wZRoRqdmWpuTXY4PW2j" alt=""><figcaption></figcaption></figure>

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](https://www.npmjs.com/package/blitzware-node-api-sdk):

{% code title="npm" overflow="wrap" lineNumbers="true" %}

```
npm install blitzware-node-api-sdk
```

{% endcode %}

{% code title="yarn" lineNumbers="true" %}

```
yarn add blitzware-node-api-sdk
```

{% endcode %}

## 3) Configure environment

Create a `.env` file:

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

## 4) Express setup

{% code lineNumbers="true" %}

```javascript
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}`)
);
```

{% endcode %}

## 5) Koa setup

{% code lineNumbers="true" %}

```javascript
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}`)
);
```

{% endcode %}

## 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:

{% code lineNumbers="true" %}

```js
// 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);
```

{% endcode %}

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

{% code lineNumbers="true" %}

```js
// 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;
```

{% endcode %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blitzware.xyz/oauth/quickstart/backend/node.js-backend-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.