Anzar SDK Documentation

Install The Typescript SDK

In a ts project run the following command to install the anzar package.

npm

$ npm install @anzar-auth/server

pnpm

$ pnpm install @anzar-auth/server

yarn

$ yarn add @anzar-auth/server

Middleware

The server SDK provides two Express middleware functions for protecting your routes using JWT tokens issued by your Anzar Auth container.

AnzarExpressRequireAuth

Verifies the JWT token and attaches the authenticated user's ID to the request object. Use this to protect any route that requires a logged-in user.

import { AnzarExpressRequireAuth } from "@anzar-auth/server";
 
const requireAuth = AnzarExpressRequireAuth({
  secret: process.env.SECRET;
  audience: process.env.AUTH0_AUDIENCE,
});

app.get("/profile", requireAuth, (req, res) => {
  res.json({ userId: req.user_id });
});

Parameters

| Parameter | Type | Default | Description | |-----------------|----------|-----------|----------------------------------------------------------------------| | secret | string | — | The secret key used to sign and verify JWT tokens | | audience | string | "web-app" | The intended recipient of the token | | algorithm | string | "HS256" | The algorithm used to verify the JWT signature | | issuerBaseURL | string | — | The base URL of the token issuer | For further reading, see the JWT specification.

Behavior

• If no token is provided → 401 { error: "No token provided" }
• If the token is invalid or expired → 403 { error: "Invalid or expired token" }
• If the token is valid → sets req.user_id from the token's sub claim and calls next()

requireRole

Verifies the JWT token and checks that the token includes a specific role. Use this to restrict routes to users with a particular permission level.

import { requireRole } from "@anzar-auth/server";

const requireAdmin = requireRole({
  secret: process.env.SECRET,
  audience: process.env.AUTH0_AUDIENCE,
}, "Admin");
 
app.delete("/admin/users/:id", requireAdmin, (req, res) => {
    // only reachable by users with the "admin" role
    res.json({ deleted: req.params.id });
  }
);

Parameters

| Parameter | Type | Default | Description | |-----------------|-----------------|-----------|----------------------------------------------------------------------| | role | User, Admin | — | The role the authenticated user must have | | secret | string | — | The secret key used to sign and verify JWT tokens | | audience | string | "web-app" | The intended recipient of the token | | algorithm | string | "HS256" | The algorithm used to verify the JWT signature | | issuerBaseURL | string | — | The base URL of the token issuer |

For further reading, see the JWT specification.

Behavior

• If no token is provided → 401 { error: "No token provided" }
• If the token is valid but the user lacks the required role → 403 { error: "Forbidden" }
• If the token is invalid or expired → 403 { error: "Invalid or expired token" }
• If the token is valid and the role matches → sets req.user_id and calls next()

Full Example

import express from "express";
import { AnzarExpressRequireAuth, requireRole } from "@anzar-auth/server";
 
const app = express();
 
const requireAuth = AnzarExpressRequireAuth({
  secret: process.env.SECRET;
  audience: process.env.AUTH0_AUDIENCE,
});

// Any authenticated user
app.get("/dashboard", requireAuth, (req, res) => {
    res.json({ message: `Welcome, user ${req.user_id}` });
  }
);
 
const requireAdmin = requireRole({
  secret: process.env.SECRET,
  audience: process.env.AUTH0_AUDIENCE,
}, "Admin");

// Admin-only route
app.get("/admin", requireAdmin, (req, res) => {
    res.json({ message: "Admin area" });
  }
);
 
app.listen(3000);

📝 Note: Make sure the SECRET used in your server matches the one configured in your Anzar Auth container, otherwise all tokens will fail verification.