Installation

Install the package

npm i better-iam

Framework peers (next, react, vue, svelte, @sveltejs/kit, react-router, @nestjs/*) are optional peer dependencies: install the ones your application already uses. Nuxt projects also install @better-iam/nuxt.

Set environment variables

Better IAM derives its signing and encryption keys from one deployment secret of at least 32 characters. Generate one with the CLI and append it to your .env file:

npx better-iam secret --env >> .env

Then add the URL your application is served from:

BETTER_IAM_SECRET=generated-value
BETTER_IAM_BASE_URL=http://localhost:3000

Better IAM does not load .env files itself. Make the variables available to every process that loads the configuration (your server, scripts, and the CLI), for example with your framework's .env support or node --env-file=.env.

Create the instance

Put the options in a configuration module whose default export is the options object. Your application and the better-iam CLI both load it, so migrations and scheduled jobs always see the same settings.

export default {
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: process.env.BETTER_IAM_BASE_URL,
  // database: added in the next step
};

Then create the one instance the rest of your server code imports:

import { betterIam } from 'better-iam';
import config from './better-iam.config.mjs';

export const iam = betterIam(config);

Frameworks expect this file in a server-only place: lib/iam.ts in Next.js, server/iam.ts in Nuxt, src/lib/server/iam.ts in SvelteKit, and app/iam.server.ts in React Router.

Configure the database

Better IAM keeps all of its records in your database through a storage adapter, passed as the database option. The three bundled adapters share one schema, so you can start on SQLite and move to PostgreSQL later.

import { postgresAdapter } from 'better-iam/adapter-postgres';

export default {
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL }),
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: process.env.BETTER_IAM_BASE_URL,
};

See Storage operations for durability settings, snapshots, and moving between databases, and Adapters and plugins to write your own adapter.

Create the tables

Run the migrations once per deployment, before the application serves traffic:

npx better-iam migrate

The CLI finds the nearest better-iam.config.mjs (or .js, .ts); pass --config PATH or set BETTER_IAM_CONFIG to use another file. migrate creates or upgrades the schema and applies plugin migrations, and it is safe to run again.

To migrate from code instead, for example when a single-process app starts, call iam.initialize() before the first request:

import { iam } from './iam';

await iam.initialize(); // creates or upgrades the schema, then runs plugin migrations

See Migrations and the migrate command.

Mount the handler

The instance exposes a Web-standard iam.handler (Request to Response) and a Node iam.nodeHandler. The browser client, passkey ceremonies, and the OAuth, SAML, and SCIM protocol mounts all reach the server through it, under the basePath option (default /api/iam). Every API method is a POST; GET serves the operational /health, /metrics (when a metrics token is configured), and /.well-known/jwks.json (when session JWTs are enabled) endpoints.

import { createIamNext } from 'better-iam/next';
import { iam } from './iam';

export const iamNext = createIamNext(iam, { loginPath: '/login' });

import { iamNext } from '@/lib/iam-next';

export const runtime = 'nodejs';
export const { GET, POST, OPTIONS } = iamNext.handlers();

Create the client

The typed client calls the mounted handler from the browser. Import the server instance with import type, so no server code reaches the bundle; every method's input and result is then inferred from your configuration.

import { createIamClient } from 'better-iam/client';
import type { iam } from './iam';

export const client = createIamClient<typeof iam>();

In a browser the client defaults to the page's origin and the /api/iam base path. Pass baseURL when the API is on another origin or when the client runs outside a browser, and basePath when you changed the server's. React, Vue, and Svelte bindings build on the same client; see Typed client.

Done

The API is live. Check that the configuration loads and the database is ready:

npx better-iam doctor

doctor reports schema, bootstrap, secret strength, durability, email transport, and scheduled-job problems, and --strict exits non-zero on any warning so you can run it in CI. See the doctor command.

A fresh database has no tenants yet. Continue with the Quickstart to bootstrap the root administrator, create an organization, and make your first authorization check.