I IntelliAuth Docs

The Node SDK has two parts:

  • requireSession — Express middleware that validates incoming bearer tokens.

  • ManagementClient — server-side admin client for backend-driven actions (look up users, suspend accounts, list applications, etc.).

Both ship from the same package.

Supported runtimes

  • Node: 18 or later (for the fetch polyfill behaviour the SDK uses).

  • Express: 4 or 5. The middleware works with both.

  • TypeScript: 4.7 or later (for req.user typing to flow correctly).

The SDK runs in any Node environment that supports ES modules — including Next.js API routes (when configured for ESM), Cloudflare Workers (with the right adapter), AWS Lambda, etc.

Install

bash
pnpm add @intelliauth/node-sdk
# or: npm install @intelliauth/node-sdk
# or: yarn add @intelliauth/node-sdk

The Node SDK is configured from environment variables by convention:

bash
# .env
INTELLIAUTH_TENANT_URL=https://banking-cymmetri.intelliauth.local
INTELLIAUTH_API_AUDIENCE=api.banking.cymmetri.com

# For the management client (M2M credentials):
INTELLIAUTH_M2M_CLIENT_ID=app_01HZX...
INTELLIAUTH_M2M_CLIENT_SECRET=<server-side-only>

Read them in your app:

ts
import { requireSession, ManagementClient } from '@intelliauth/node-sdk'

const auth = requireSession({
  tenantUrl: process.env.INTELLIAUTH_TENANT_URL!,
  audience: process.env.INTELLIAUTH_API_AUDIENCE!,
})

const cp = new ManagementClient({
  tenantUrl: process.env.INTELLIAUTH_TENANT_URL!,
  clientId: process.env.INTELLIAUTH_M2M_CLIENT_ID!,
  clientSecret: process.env.INTELLIAUTH_M2M_CLIENT_SECRET!,
})

The SDK validates required env vars at construction; missing ones throw immediately with a clear message.

Never ship the M2M secret to the browser

The clientSecret for the management client is server-side only. If you bundle it into a frontend build, anyone who reads the bundle has full admin access to your tenant. Use environment variables that aren't prefixed with VITE_ / NEXT_PUBLIC_ / REACT_APP_, and verify your bundler isn't leaking them into client-side chunks.

JWKS caching

The session middleware caches your tenant's JWKS (the public keys it uses to verify token signatures) for 15 minutes by default. You can tune that:

ts
requireSession({
  tenantUrl: '...',
  audience: '...',
  jwksCacheTtlSeconds: 3600, // 1 hour
})

Longer TTL = fewer JWKS fetches but slower key-rotation propagation. The default is conservative; production deployments often use 1 hour or longer.

Bundle size

The SDK adds ~28 KB minified to your server bundle. No dependencies beyond jose (for JWT verification) and cross-fetch (for the JWKS endpoint).

See also