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

Middleware

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

📝 Note: JWT vs. Session

Depending on what Authentication strategy you choose, use these middleware functions accordingly

Jwt

require_auth

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 { requireAuth, JwtAuth } from "@anzar-auth/server";
 
const jwt = JwtAuth({
  audience: process.env.ANZAR_AUDIENCE,
  issuerBaseURL: process.env.ANZAR_ISSUER,
});

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

Parameters

| Parameter | Type | Default | Description | |-----------------|----------|-----------|----------------------------------------------------------------------| | audience | string | — | The intended recipient of the token | | algorithm | string | "RS256" | 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()

require_role

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, JwtAuth } from "@anzar-auth/server";

const jwt = JwtAuth({
  audience: process.env.AUTH0_AUDIENCE,
  issuerBaseURL: process.env.ANZAR_ISSUER,
});

app.delete("/admin/users/:id", requireRole(jwt, ["user"], ["posts:read", "posts:write"]), (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 | | audience | string | — | The intended recipient of the token | | algorithm | string | "RS256" | 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()

Session

require_auth

Verifies the session and attaches the authenticated user's ID to the request object. Use this to protect routes when using session-based authentication.

import { requireAuth, SessionAuth } from "@anzar-auth/server";
 
const session = SessionAuth({ url: "localhost:3000" });

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

Behavior

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

require_role

Verifies the session and checks that the session includes a specific role. Use this to restrict routes to users with a particular permission level when using session-based authentication.

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

const session = SessionAuth({ url: "localhost:3000" });

app.delete("/admin/users/:id", requireRole(session, ["user"], ["posts:read", "posts:write"]), (req, res) => {
    // only reachable by users with the "admin" role
    res.json({ deleted: req.params.id });
  }
);

Behavior

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

Full Example

import express from "express";
import { JwtAuth, requireAuth, requireRole, SessionAuth } from "@anzar-auth/server";
 
const app = express();
app.use(cors({ origin: 'http://localhost:5173', credentials: true }));

const jwt = JwtAuth({
  audience: "web-app",
  issuerBaseURL: "http://locahost:3000",
  algorithm: "RS256",
});
 
// Any authenticated user
app.get("/dashboard", requireAuth(jwt), (req, res) => {
    res.json({ message: `Welcome, user ${req.user_id}` });
  }
);

// Admin-only route
app.get("/admin", requireRole(jwt, ["admin"], ["users:write"]), (req, res) => {
    res.json({ message: "Admin area" });
  }
);

app.listen(5000);