Architecture overview

Better IAM is the identity layer of your application: it knows who is signing in, which organization they belong to, and what they may do. Instead of calling a hosted service, you run it as a set of packages inside your own process, against your own database. This page explains how those packages fit together and what happens to every request, so the rest of the documentation has a map to hang on.

Key terms

These words appear on almost every page. Throughout the documentation, a dotted underline marks a term; select it for a short definition. The glossary lists every term.

How the packages fit together

Better IAM is a set of layered packages. Each layer depends only on the contracts below it, so you can read, test, and replace them one at a time.

• The pure core (@better-iam/core) defines policies, shared types, and the IamStore storage contract.
• SQL adapters implement IamStore for SQLite, libSQL, and PostgreSQL.
• The authentication and protocol packages (OAuth/OIDC, SAML, SCIM) operate on that contract.
• The server (@better-iam/server) composes authentication, authorization, provisioning, and transport into one object: betterIam(options).
• The client (@better-iam/client) contains only a fetch-based transport and type inference, so it is safe to ship to browsers.
• The umbrella package better-iam re-exports everything through subpath imports without eagerly importing the protocol implementations. A protocol is loaded only when you import its subpath.

Public surfaces

You create one Better IAM instance with betterIam(options) and import it wherever your server code needs identity or authorization. The object it returns is the whole public surface. Most applications use a handful of its members:

api is organized in groups, one per kind of record. api.auth holds what end users do for themselves (sign in, manage factors and sessions). The other groups are provisioning operations that administrators and your server perform on a tenant:

Governance groups (certifications, separation of duties, role mining, and more) and federation groups build on these. The API reference lists every group and method with its HTTP route and TypeScript signature.

One operation, three ways to call it

Every group method takes (credential, input) on the server. The browser client and HTTP call the same operation, with the request itself as the credential.

import { iam } from './iam';

// The credential is the incoming request's headers (a cookie or bearer token), or { token }.
const credential = { headers: request.headers };
await iam.api.identities.invite(credential, { tenantId, email: 'alice@example.com' });

The credential says who is calling. It contains request headers (with a session cookie or a bearer token) or an opaque token, never caller-supplied identity claims such as a user ID. The server looks the credential up and resolves it to the current identity and session records itself, so a caller cannot claim to be someone else.

A few operations happen before anyone holds a credential, so they are public:

• tenants.lookup resolves an organization's sign-in alias, such as acme, for a login page.
• domains.discover finds the organization that owns an email domain, for "sign in with your work email".
• tenants.acceptInvitation and identities.acceptInvitation redeem an invitation and create the invitee's account.
• The sign-in ceremonies in api.auth, such as signIn and verifyMfa, are public for the same reason.
• sts.assumeRoleWithWebIdentity exchanges a token from an external OpenID Connect provider for a role session; that external token is its credential.

Deployment-only capabilities

Some members exist for trusted server code and deployment tooling only:

Module layout

You do not need the module layout to use Better IAM, but it helps when you read the source, debug a decision, or write a plugin. The server package is a set of small modules that betterIam() composes in src/index.ts:

Modules reach each other through the context at call time (ctx.decisions.decide(...)). That keeps them free of import cycles and lets you read each one on its own.

The other packages follow the same idea:

• Authentication. service/base.ts holds configuration and the session core. sessions.ts, account.ts, passwordless.ts, mfa.ts, and passkeys.ts each extend the previous class with one feature. outbox.ts and rate-limit.ts are plain modules.
• SCIM separates its filter grammar, discovery documents, provisioning logic, and HTTP handler.
• OAuth separates the provider adapter from the provider service.

The request pipeline

Every operation runs through the same pipeline, whether it comes from a browser, a server action, the CLI, or a SCIM connector: resolve the credential, authorize, apply the change in one serialized transaction, and append an audit event. Direct calls and HTTP enter the same operation service.

Having one path is what makes the guarantees hold everywhere. A permission check, a revocation, or an audit rule enforced in the pipeline cannot be skipped by calling the API a different way.

No cross-request permission cache exists. Token validity and the current role and policy state are checked on every use, so a revocation takes effect on the next request. See data and consistency.

Next steps