Deployment

A Better IAM deployment is your application process plus a database. There is no separate service to run: you construct one instance with betterIam(), mount its HTTP handler, run migrations at deploy time, and schedule a few worker jobs. This page covers the runtime, the options you must decide on, and the deploy sequence. The configuration reference lists every option.

Runtime

• Node.js 22.12 or a newer supported LTS release. The CI matrix covers Node 22 and 24 on Windows and Linux.
• Database drivers: each storage adapter bundles its driver. SQLite uses a native driver (better-sqlite3), libSQL uses @libsql/client (local files, embedded replicas, and remote Turso or sqld databases), and PostgreSQL uses pg.
• No edge runtimes for the complete authentication and protocol server. The OAuth issuer in particular needs Node's HTTP interfaces (see protocol mounts).

What every production instance sets

Most options have safe defaults, but a few describe your deployment and have no sensible default. Configuration is validated once, when betterIam() runs, and invalid values throw INVALID_CONFIG. These are the options you cannot leave to defaults in production:

Protocol keys are separate, explicit inputs: the OAuth provider's signing JWKs, its 32-byte encryption key and cookie keys, SAML signing and decryption keys, and the session-JWT keys in sts.jwt. No production signing key is ever generated inside a request handler, so supply each one from your secret store and keep it stable across replicas and restarts.

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';
import { sendEmail, sendSms } from './delivery';

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  secret: process.env.BETTER_IAM_SECRET!,
  // Only during a secret rotation: the old value(s), comma-separated.
  previousSecrets: process.env.BETTER_IAM_PREVIOUS_SECRETS?.split(',').filter(Boolean),
  baseURL: 'https://identity.example.com',
  trustedOrigins: ['https://app.example.com'],
  authentication: {
    appName: 'Acme Cloud',
    sendEmail,
    sendSms,
    passkeys: { rpID: 'example.com', rpName: 'Acme Cloud' },
  },
  http: {
    // Trust this header only because your own proxy sets it.
    clientInfo: (request) => ({
      ip: request.headers.get('x-real-ip') ?? undefined,
      userAgent: request.headers.get('user-agent') ?? undefined,
    }),
  },
  observability: { metrics: { bearerToken: process.env.METRICS_TOKEN } },
});

Environment variables

Better IAM reads configuration from your code, not from the environment. The variables below are the ones the CLI, the generated starter configuration, and the test suites use.

Deploy sequence

The same few steps run the first time you deploy and, minus the one-time ones, on every release after that:

better-iam init --database postgres --config better-iam.config.mjs
better-iam migrate --config better-iam.config.mjs
better-iam bootstrap --config better-iam.config.mjs
better-iam doctor --config better-iam.config.mjs --strict

better-iam recover-root uses the same three environment variables to create a new root administrator in the root tenant when nobody can sign in as root any more. It is recorded as root:recover, and the new account must enroll MFA too. Treat access to the configuration, the database credentials, and the ability to run recover-root as root-equivalent.

The CLI

The better-iam CLI is how operators and schedulers act on a deployment without writing code: setting it up, running the recurring jobs, checking the audit log, moving data, and rotating secrets. It loads the same configuration file your application uses, so it always sees the same database and secret. Every command is listed with its flags in the CLI reference.

Most commands are deployment operations: they work on storage directly and need no credential, which is why the configuration file and database credentials must be protected like root. The tenant administration commands instead act as the session or API key in BETTER_IAM_TOKEN, so they are authorized and audited exactly like the same call from the console. Two commands, init and audit-verify-archive, touch no database at all.

The 29 commands fall into five groups.

Setup and health

Scheduled jobs

Scheduled jobs explains each job in detail.

Audit

Storage and secrets

Tenant administration (acts as BETTER_IAM_TOKEN)

A failed command prints CODE: message and exits 1; unexpected failures print a generic message rather than internal details. Secrets are never accepted as command-line arguments.

Next steps