Introduction

Better IAM gives an application the identity layer that is usually bought as a hosted service: multi-tenant organizations, sign-in with every modern method, fine-grained authorization, governance, and enterprise federation. It is a library, not a SaaS. It runs in your process, stores its data in your PostgreSQL, SQLite, or libSQL database, and exposes a typed API to your server and browser code.

You create one instance with betterIam(), giving it a database, a deployment secret, and the URL it is served from, and import that instance wherever your server code needs identity or authorization:

import { betterIam } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';

export const iam = betterIam({
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: 'https://identity.example.com',
});

Why it exists

Most business software eventually needs the same identity features: customers are organizations rather than individuals, each organization wants its own roles and its own single sign-on, security teams ask who can do what and who changed it, and enterprise buyers expect SCIM provisioning, MFA policies, and an audit trail. Teams usually assemble this from several services: a hosted sign-in provider, a separate authorization service, and later a governance or provisioning tool. That works, but it has costs:

• Your identity data lives somewhere else. People, sessions, and roles sit in a vendor's database, so every permission check is a network call, and keeping that data consistent with your own records is your problem.
• Authorization is disconnected from your data. Deciding "may Alice approve this invoice?" needs the invoice's owner and amount, which the external service does not have.
• Each service has its own model. Tenants, roles, and audit logs are defined three times and reconciled by hand.

Better IAM takes the other approach: it is a library that runs inside your application and stores everything in your database, in the same transactions as your own writes. One tenant model, one authorization engine, and one tamper-evident audit log cover sign-in, access decisions, governance, and federation, all behind a single typed API.

What it covers

How it fits together

Every operation, whether it comes from a browser, a server action, the CLI, or a SCIM connector, runs through the same pipeline:

1. Resolve the credential. A session cookie, bearer token, API key, or assumed role becomes a principal: who is calling, how they signed in, and whether they used MFA.
2. Authorize. The principal's roles, policies, and boundaries in that tenant decide whether the action is allowed.
3. Apply the change in one transaction in your database, so a failure leaves nothing half done.
4. Record it. A hash-chained audit event is appended in the same transaction and then fans out to webhooks, in-process subscribers, and metrics.

Because every API call takes this one path, no API call bypasses authorization or the audit log, and an administrator using the console is held to the same rules as your own API calls. Deployment operations that take no credential (migrations, root bootstrap, scheduled jobs) run from your server or the CLI, not over the API.

Who makes it

Better IAM is created and maintained by Sean Filimon. Every package is open source under the Apache License 2.0.

How these docs are organized

Docs for AI

These docs are written to be read by coding agents as well as people: every page is available as Markdown, the site publishes /llms.txt and /llms-full.txt, and a read-only MCP server lets an assistant search pages and look up API methods, exports, and error codes while it works. See Use the docs with AI to connect Claude Code, Cursor, or VS Code.

Where to go next