I IntelliAuth Docs

The Node SDK is for server-side code that talks to IntelliAuth. Two main use cases:

  • Manage IntelliAuth resources from a backend — create users programmatically, rotate application credentials, query the audit log, sync roles. The "management client" handles this.

  • Validate sessions and access tokens on incoming requests — your Express / Fastify / NestJS app needs to know whether the caller is signed in and which scopes they hold. The "Express middleware" handles this.

The two surfaces are independent — pick either, or both, depending on your needs.

If you are writing browser code, use the React SDK instead. If you are writing Go, Python, or Ruby today, talk to the IntelliAuth REST API directly using the API reference.

Install

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

ESM and CommonJS both work. TypeScript types ship in the package; no @types/ install needed.

Node 18 or higher. Earlier versions lack the fetch global the SDK relies on.

The two surfaces

Surface

Role

Topic

Management client

Programmatic admin operations against the tenant's API. Uses client credentials under the hood.

Management client

Express middleware

Drop-in middleware that validates the bearer token on incoming requests, surfaces req.user, and gates routes by scope.

Express middleware

Minimal management example

ts
import { IntelliAuthManagement } from '@intelliauth/node-sdk'

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

const user = await mgmt.users.create({
  email: 'new.user@cymmetri.com',
  name: 'New User',
  password: 'a temporary one',
  password_must_be_reset: true,
})

The management client manages its own access token internally — token request, caching, refresh on expiry. You don't need to think about it.

Minimal middleware example

ts
import express from 'express'
import { intelliAuth } from '@intelliauth/node-sdk/express'

const app = express()

app.use(intelliAuth({
  tenantUrl: process.env.INTELLIAUTH_TENANT_URL!,
  audience: 'https://api.cymmetri.com',
}))

app.get('/me', (req, res) => {
  res.json({ user: req.user, scopes: req.scopes })
})

app.get('/admin/reports', intelliAuth.requireScope('audit:read'), (req, res) => {
  // Only reachable if the access token carries audit:read.
  res.json({ ... })
})

intelliAuth() validates the Authorization: Bearer <token> header on every request, attaches req.user and req.scopes, and rejects invalid tokens with a 401. requireScope() adds a per-route scope check.

What the Node SDK does NOT do

  • Serve a sign-in UI. That is the browser's job (and the React SDK's). The Node SDK assumes the user has signed in elsewhere and that you are validating the resulting token.

  • Replace your application's HTTP framework. The Express middleware integrates with Express; Fastify / Koa / NestJS adapters can be built on the underlying verifyAccessToken primitive.

  • Cache user records. The management client makes a fresh API call on each operation. If you need caching for high-throughput admin operations, wrap the client with your own cache (Redis is the common pick).

Stability

The Node SDK is v0.x today — usable in production, but the minor-version bumps may carry breaking changes until v1. Read the changelog before upgrading minor versions.

What's next

See also