# Docs - Guides: Concepts, authentication, and authorization - **Getting started** - [Introduction](/docs/guides): Better IAM is an embeddable TypeScript platform for authentication, identity provisioning, and access management that runs inside your application, on your database. - [Quickstart](/docs/guides/quickstart): Install Better IAM, migrate a database, bootstrap the root, create an organization, and make your first authorization check. - [Installation](/docs/guides/installation): Install the umbrella package or individual @better-iam packages, choose a database adapter, and configure your runtime. - [Frequently asked questions](/docs/guides/faq): Short, plain answers to the questions people ask before adopting Better IAM, with links to the details. - **Foundations** - Core concepts - [Architecture overview](/docs/guides/concepts): How Better IAM is put together, from the packages and the surfaces of betterIam() to the pipeline every operation runs through. - [Tenants and identities](/docs/guides/concepts/tenants-and-identities): Tenant trees, isolated identity directories, invitations, sign-in aliases, root administration, account linking, and what suspension and deletion do. - [Resources and catalog](/docs/guides/concepts/resources-and-catalog): The vocabulary policies speak: actions, resource types, application-owned and managed resources, relations, and tenant-defined types. - [Data and consistency](/docs/guides/concepts/data-and-consistency): How Better IAM stores its records, why every write is serialized, how side effects leave through the outbox, and how plugins and protocols compose. - Authentication - [Authentication](/docs/guides/authentication): How people and services prove who they are in Better IAM, how a sign-in flows from first factor to session, and where each method is configured. - [Sign-in methods](/docs/guides/authentication/sign-in-methods): Passwords and password screening, self-registration, magic links, email and SMS codes, federated sign-in, API keys, and assumed roles. - [Multi-factor authentication](/docs/guides/authentication/mfa): When a second factor is required, how people complete it with TOTP, recovery codes, emailed codes, or passkeys, and how remembered devices and step-up work. - [Passkeys](/docs/guides/authentication/passkeys): Register passkeys, sign in with them (including discoverable autofill sign-in), use them as a second factor, and let people name and manage them. - [Sessions](/docs/guides/authentication/sessions): Database sessions with absolute and idle lifetimes, device metadata, recent authentication, sign-out everywhere, session caps, and sign-in records. - [Verification and recovery](/docs/guides/authentication/recovery): Email verification, password reset and change, email and phone changes, lost second factors, and clearing lockouts. - [Tenant authentication policy](/docs/guides/authentication/tenant-policy): Per-organization sign-in rules - required MFA, allowed methods, password rules, session limits, remembered devices, IP allowlists, session binding, and network blocks. - [Impersonation](/docs/guides/authentication/impersonation): Audited "view as" sessions that let support staff see exactly what a member sees, restricted to what both people may do and visible everywhere. - [HTTP and configuration](/docs/guides/authentication/http): How the HTTP handler serves authentication - routes, cookies, CSRF and Origin checks, rate limits, headers, request IDs - plus every authentication option and email template. - Authorization - [Authorization](/docs/guides/authorization): How Better IAM decides whether a principal may perform an action on a resource, and where roles, policies, boundaries, and relationships fit in. - [Permission catalog](/docs/guides/authorization/catalog): The actions and resource types policies may name, from built-in iam:* actions to product, plugin, and tenant-defined types and their resources. - [Roles and bindings](/docs/guides/authorization/roles): Custom roles built from permission lists or policy documents, role inheritance, bindings to people and groups, and delegated grant authorities. - [Policy documents](/docs/guides/authorization/policies): Versioned JSON policies, from statement fields and limits to how grants and boundaries combine, policy variables, versions, testing, and lint. - [Conditions](/docs/guides/authorization/conditions): Every condition operator, how values combine, negation and missing-key rules, and the context keys the server provides to policies. - [Relationships](/docs/guides/authorization/relationships): Relationship-based access control. Declare relations on resource types, record who holds them, and write policies that read resource.relations. - [Batches and reverse queries](/docs/guides/authorization/queries): Check many actions at once with authorizeMany, list the resources a caller may act on with listAccessible, and render UI from advisory decisions. - [Access reviews](/docs/guides/authorization/reviews): Explain and review access without granting it. Simulate a decision, list who can act on a resource, see a person's effective actions, and scan for risk. - [Separation of duties](/docs/guides/authorization/separation-of-duties): Declare roles nobody may hold together, block every grant that would combine them, and report the conflicts that already exist. - [Temporary access](/docs/guides/authorization/temporary-access): Access that ends, starts later, or applies only in business hours, plus access requests, role sessions, session tokens, web-identity federation for workloads, and expiring API keys. - **Access lifecycle** - Privileged access - [Privileged access](/docs/guides/privileged-access): Keep standing privilege low and access time-bound with eligible roles, expiring identities, access packages, reports, and configuration as code. - [Just-in-time elevation](/docs/guides/privileged-access/elevation): Eligible bindings that people activate for a bounded time, with justification, MFA, approval, approver groups, and tenant-wide floors. - [Access lifecycle](/docs/guides/privileged-access/lifecycle): Time-bound identities, temporary memberships, future-dated bindings, API key hygiene, and offboarding that removes all access in one call. - [Access packages](/docs/guides/privileged-access/access-packages): Bundle roles and group memberships into packages that administrators assign, members request with approval, and rules grant automatically. - [Automatic assignment](/docs/guides/privileged-access/automatic-assignment): Birthright access with package rules that grant a package to every matching identity and remove it from holders who stop matching. - [Access report](/docs/guides/privileged-access/access-report): One document with what ends soon, what is elevated now, and which keys nobody uses, plus digest emails to owners and expiry reminders. - [Configuration as code](/docs/guides/privileged-access/config-as-code): Export, plan, and apply a tenant's roles, policies, groups, teams, bindings, packages, agents, and guardrails as one reviewed document. - Governance - [Governance](/docs/guides/governance): The loop that keeps access correct over time, from measuring usage and mining roles to reviews, guardrails, terms of use, and self-service. - [Usage and role mining](/docs/guides/governance/usage-and-mining): Record which actions people actually use, right-size roles, and mine the directory for redundant grants, bundles, and peer outliers. - [Certifications](/docs/guides/governance/certifications): Access certification campaigns where reviewers or managers keep or revoke each binding, with reminders, usage-based recommendations, and auto-close. - [Change safety](/docs/guides/governance/change-safety): Preview who gains and loses what before editing a role or policy, and enforce access invariants that no change may break. - [Terms of use](/docs/guides/governance/agreements): Versioned agreements such as acceptable-use policies that members accept, with enforcement through ordinary policy statements. - [Access paths](/docs/guides/governance/access-paths): Tell a denied person what they could do themselves, such as step up to MFA, accept terms, activate a role, or request a package. - [Scheduling](/docs/guides/governance/scheduling): The jobs, CLI commands, and cadences that keep governance and the access lifecycle running without manual work. - Events and audit - [Events and audit](/docs/guides/events): Every audit record is an event, recorded in the transaction that made the change and fanned out to subscribers, webhooks, and the audit chain. - [Webhooks](/docs/guides/events/webhooks): Signed HTTPS deliveries of audit events with outcome and resource filters, retries with backoff, delivery history, and redelivery. - [Lifecycle events](/docs/guides/events/lifecycle-events): Every access lifecycle event, from role activations and offboarding to package rules and invariants, with what it means and the metadata it carries. - [Audit chain](/docs/guides/events/audit-chain): The tamper-evident, hash-chained audit log per tenant, and how to verify it, export it, archive it continuously, and prune it with checkpoints. - **Organizations** - [Feature flags](/docs/guides/feature-flags): Turn product features on and off per organization without a deploy, from the platform or from each organization, and gate the same features in the UI and in authorization. - [Onboarding](/docs/guides/onboarding): Checklists for new members and new tenants, defined by the platform and customized by each organization and project. - [Teams and departments](/docs/guides/teams-and-departments): Nested teams whose maintainers manage membership and take join requests, and the department tree with heads that policies and approvals follow. - [Billing and spend](/docs/guides/billing): Usage meters, rate cards, and spend by person, team, department, project and organization, with budgets, plans and subscriptions, and Stripe-style invoicing. - **AI agents** - [AI agents](/docs/guides/ai-agents): Treat AI agents as accounts with a responsible sponsor, a ceiling on what they may do, and short delegated sessions when they act for a person. - [Model access and budgets](/docs/guides/inference): Decide who may call which AI models, cap what people, teams, and agents spend, meter every call, and keep provider keys away from callers with a gateway. - **Cookbook** - Recipes - [Recipes](/docs/guides/recipes): Short, copy-ready solutions for common identity and access problems, from sharing and MFA rules to offboarding, plan limits, and audit archiving. - [Sharing and access questions](/docs/guides/recipes/sharing-and-reviews): Recipes for sharing with relationships, answering who can do what, testing and rolling back policies, time-bound roles, access paths, and guardrails. - [Sign-in and devices](/docs/guides/recipes/sign-in-and-devices): Recipes for per-organization MFA and sign-in method rules, remembering trusted browsers after MFA, device lists, sign-out everywhere, and incident response. - [Support and privacy](/docs/guides/recipes/support-and-privacy): Recipes for letting support staff view the product as a member, exporting everything stored about a person, and rendering the outbox's emails. - [Tenancy and limits](/docs/guides/recipes/tenancy-and-limits): Recipes for SaaS plan limits and usage metering, bulk onboarding with directory attributes from SCIM, moving people over from another login system, and storing data in libSQL or Turso. - [Access lifecycle](/docs/guides/recipes/access-lifecycle): Recipes for just-in-time elevation with approvals, scheduled deactivation for contractors, API key hygiene, configuration as code, and offboarding. - [Operations recipes](/docs/guides/recipes/operations): Recipes for verifying and archiving the audit chain, calling downstream services with stateless assertions, observing latency, and filtering and redelivering webhooks. - Frameworks: Next.js, React, Vue, Nuxt, SvelteKit, NestJS, and more - [Frameworks](/docs/frameworks): What each framework integration does for you, and how the typed client, React, Vue, Next.js, Nuxt, SvelteKit, React Router, NestJS, and Node ones compare. - **Client** - [Typed client](/docs/frameworks/client): createIamClient gives browser and Node code a typed API inferred from your server instance, with a session store and passkey helpers. - [React](/docs/frameworks/react): IamProvider, useSession, useAuthorize, Can, and self-service hooks for rendering React UI from the signed-in session and advisory decisions. - [Vue](/docs/frameworks/vue): The @better-iam/vue plugin, composables, and IamCan component, with server-rendered sessions and hydrated decisions for Vue 3.3 and later. - **Full-stack** - Next.js - [Next.js](/docs/frameworks/nextjs): Set up @better-iam/next in an App Router project, mount the IAM API, and read the session in server components, layouts, and client components. - [Guards](/docs/frameworks/nextjs/guards): Protect Next.js pages, layouts, and route handlers with page, requireSession, require, and route, and render by permission with batched checks. - [Server actions and forms](/docs/frameworks/nextjs/server-actions): Call Better IAM from Next.js server actions with the in-process client, guard mutations with action(), and drop in sign-in, step-up, and reset forms. - [Organizations in the URL](/docs/frameworks/nextjs/organizations): Serve each organization under its own /[org] path with requireTenantSession, and send visitors from other organizations to the right sign-in. - [Middleware](/docs/frameworks/nextjs/middleware): Redirect signed-out visitors at the edge with createIamMiddleware, keep public paths open, and forward the requested path so ?next= fills itself. - [Advanced](/docs/frameworks/nextjs/advanced): Step-up, API keys in route handlers, assertions and webhooks for other services, client refresh, the Pages Router, and background delivery in Next.js. - [Nuxt](/docs/frameworks/nuxt): The @better-iam/nuxt module mounts the IAM API in Nitro, renders sessions on the server, guards pages from page meta, and auto-imports helpers. - [SvelteKit](/docs/frameworks/sveltekit): A handle hook that serves the IAM API and guards sections, locals.iam for loads and form actions, and Svelte 4 and 5 stores for the browser. - [React Router](/docs/frameworks/react-router): Root middleware, guarded loaders and actions, and an API resource route for React Router framework mode (v7.9+ and v8), with React hooks in the browser. - **Server** - [NestJS](/docs/frameworks/nestjs): IamModule, a guard that authenticates every request, @Authorize and other decorators, audit event handlers, assertions, and testing for NestJS 11 and 12. - [Express, Hono, and Fastify](/docs/frameworks/node): Middleware that serves the IAM API, adds req.iam helpers, guards routes, and maps refusals to JSON or redirects, with a core for other Node frameworks. - Federation: OAuth, OIDC, SAML, SCIM, and Shared Signals - [Federation](/docs/federation): Connect enterprise identity providers, act as an identity provider for your own apps, and provision people in and out with standard protocols. - [Enterprise onboarding](/docs/federation/enterprise-onboarding): Take one customer organization from "we use Okta or Entra ID" to SSO, directory provisioning, app provisioning, and end-to-end offboarding. - **Sign-in** - [OAuth and OIDC sign-in](/docs/federation/oauth-sign-in): Sign people in with Google, GitHub, Microsoft Entra ID, any OpenID Connect provider, or a plain OAuth2 provider, with PKCE and explicit account linking. - [SAML](/docs/federation/saml): Accept SAML 2.0 single sign-on from Okta, Entra ID, ADFS, and Google Workspace, with tenant-managed connections, metadata import, and IdP-initiated login. - **Provide identity** - [OAuth/OIDC provider](/docs/federation/oauth-provider): Run a tenant-aware OAuth 2.0 and OpenID Connect authorization server for your own apps, CLIs, devices, and service accounts. - [Resource servers and tokens](/docs/federation/oauth-resource-servers): Issue audience-restricted JWT access tokens for your APIs, verify them offline, bind them to keys with DPoP, and delegate calls with token exchange. - [Dynamic registration and MCP](/docs/federation/mcp-authorization): Let MCP hosts and other self-configuring clients discover your authorization server, register with RFC 7591, and call your protected APIs. - [Shared Signals](/docs/federation/shared-signals): Push signed CAEP and RISC security events about a tenant's people to SIEMs, applications, and partner IdPs as sessions end and accounts change. - **Provisioning** - [SCIM inbound](/docs/federation/scim): Let an organization's directory create, update, deactivate, and delete its people and groups through connection-scoped SCIM 2.0 endpoints. - [SCIM outbound](/docs/federation/scim-outbound): Push a tenant's members and groups to downstream SaaS applications over SCIM 2.0, with previews, account adoption, and automatic deprovisioning. - Operations: Deploy, secure, observe, and extend - [Operations](/docs/operations): The production checklist for Better IAM, from runtime and secrets to storage, scheduled jobs, observability, and your security responsibilities. - Deployment - [Deployment](/docs/operations/deployment): Runtime requirements, the betterIam() options every production instance sets, environment variables, and the deploy sequence with the CLI. - [Configuration reference](/docs/operations/deployment/configuration): Every top-level betterIam() option, grouped by area, with what it controls, its default, when you would change it, and the rule enforced at startup. - [Sign-in addresses and regions](/docs/operations/deployment/hosts-and-regions): Give every organization its own sign-in address (a subdomain or a verified custom hostname), pin requests on it to that organization, and serve each organization from its home region. - [Database operations](/docs/operations/deployment/database): Migrations, transactions, durability, indexes, upgrades, backups, and PostgreSQL integration checks for the database behind Better IAM. - [Secrets and keys](/docs/operations/deployment/secrets): What the deployment secret protects, how previousSecrets and rotate-secrets rotate it without signing anyone out, and how assertion and protocol keys fit in. - [Protocol mounts](/docs/operations/deployment/protocol-mounts): Mount the IAM HTTP handler and the OAuth, SAML, and SCIM protocol services in a host application, and what the handler enforces on every request. - [Build and release](/docs/operations/deployment/releases): How a Better IAM release is checked, packed, smoke-tested as installed tarballs, versioned in lockstep, and prepared for publication. - [Storage adapters](/docs/operations/storage): Choose and configure the PostgreSQL, SQLite, or libSQL/Turso adapter, move a deployment between databases with snapshots, and read what doctor reports. - [Scheduled jobs](/docs/operations/jobs): The worker jobs a deployment schedules (outbox, purge, sweep, reconcile, digest, remind, certifications, invariants, audit archive) with cadences and results. - [Observability](/docs/operations/observability): Timing spans through observability.onSpan, built-in Prometheus metrics behind a bearer token, the health endpoint, request IDs, and what to alert on. - [Security model](/docs/operations/security): Better IAM's trust boundaries, root authority and delegation, authentication guarantees, external identity rules, and the responsibilities that stay with operators. - [Adapters and plugins](/docs/operations/extensions): The IamStore contract and conformance suite for new storage adapters, and the plugin contract for actions, resource types, endpoints, hooks, and context. - Reference: Server API, package exports, CLI, errors, and changelog - [Reference](/docs/reference): Generated reference for the server API, package exports, the CLI, error codes, packages, and the changelog, extracted from the repository. - Server API - [API reference](/docs/reference/api): Every method of the Better IAM server API: 45 groups and 417 methods, what each does, its HTTP route, and its TypeScript signature. - [accessPaths](/docs/reference/api/access-paths): Access paths tell a denied person what they can do on their own to be allowed, such as stepping up to MFA or requesting a package. - [accessRequests](/docs/reference/api/access-requests): Access requests let members ask for specific roles instead of asking an administrator to bind them by hand. - [actions](/docs/reference/api/actions): Actions are the names that roles and policies allow or deny, such as iam:groups:update or documents:write. - [agents](/docs/reference/api/agents): An agent is an AI agent registered as an account of its own: an identity of kind agent that a person answers for. - [agreements](/docs/reference/api/agreements): Agreements are versioned terms of use that a tenant asks its members to accept: an acceptable-use policy, an NDA, data-handling rules. - [analysis](/docs/reference/api/analysis): Access analysis scans a tenant's configuration for risky or stale access, such as administrators without MFA or dormant accounts that still hold roles. - [assertions](/docs/reference/api/assertions): Assertions are short-lived signed tokens that tell another service who is calling: the caller's identity, tenant, roles, groups, and whether they used MFA. - [audit](/docs/reference/api/audit): The audit log records who did what in a tenant; this group searches it, verifies its tamper-evident hash chain, and exports it for archiving. - [auth](/docs/reference/api/auth): The auth group signs people in and lets them manage their own account security: passwords, one-time codes, passkeys, MFA, sessions, and recovery. - [authorities](/docs/reference/api/authorities): Grant authorities delegate the right to hand out access, with a ceiling on what anything granted under them may ever allow. - [billing](/docs/reference/api/billing): Billing tells an organization what it spends, on what, and who spent it: usage recorded on meters is priced from a rate card per billing account and month, the… - [bindings](/docs/reference/api/bindings): Bindings give a role to a person, service account, or group, and control when that role actually applies. - [certifications](/docs/reference/api/certifications): Certification campaigns turn periodic access reviews into recorded decisions. - [config](/docs/reference/api/config): Configuration as code: export a tenant's access model as one JSON document, review changes to it, and apply it the same way to staging and production. - [credentials](/docs/reference/api/credentials): Credentials manages API keys: opaque bearer tokens that let a service account call Better IAM and your product without a person signing in. - [delegations](/docs/reference/api/delegations): A delegation lets one AI agent act for one person, within a scope and for a limited time. - [departments](/docs/reference/api/departments): Departments are the organization's reporting structure: Engineering, Finance, Sales, and their sub-departments. - [domains](/docs/reference/api/domains): Verified email domains let an organization prove it owns a domain such as acme.com, so your sign-in page can find the right tenant from a work email address. - [features](/docs/reference/api/features): Feature flags turn product features on and off per tenant without a deploy. - [groups](/docs/reference/api/groups): Groups let you grant access to many people at once. - [hostnames](/docs/reference/api/hostnames): Custom hostnames let an organization sign in at an address of its own, such as login.acme.com, instead of the subdomain the deployment gives it (acme.signin.ex… - [identities](/docs/reference/api/identities): Identities are the people and service accounts that sign in to a tenant, and this group manages them from invitation to offboarding. - [impact](/docs/reference/api/impact): Impact previews show who would gain or lose which actions before you edit a role or policy or delete a role. - [inference](/docs/reference/api/inference): Decides which people, service accounts, and AI agents may call which AI models, caps what they spend, and meters every call. - [invariants](/docs/reference/api/invariants): Access invariants are guardrails: statements about who must never, or must always, be able to perform an action on a resource. - [links](/docs/reference/api/links): Account links connect a person's separate accounts in different tenants so your app can offer an account switcher. - [oidcProviders](/docs/reference/api/oidc-providers): OIDC providers are the external token issuers a tenant trusts for web-identity federation: GitHub Actions, GitLab, a Kubernetes cluster, or a cloud workload id… - [onboarding](/docs/reference/api/onboarding): Onboarding flows are checklists for newcomers, customized at every level of the tenant tree. - [packages](/docs/reference/api/packages): Access packages bundle roles and group memberships that are granted, requested, and removed together. - [policies](/docs/reference/api/policies): Policies are named, versioned policy documents that roles attach to grant access. - [relationships](/docs/reference/api/relationships): Relationships record that a person or group stands in a named relation, such as owner or viewer, to one resource. - [reports](/docs/reference/api/reports): The access report gathers a tenant's access-lifecycle state in one document: what is about to end, who is elevated right now, and which API keys nobody uses. - [resourceTypes](/docs/reference/api/resource-types): Resource types let a tenant describe its own kinds of resources at runtime, with their actions, typed attributes, relations, and parent. - [resources](/docs/reference/api/resources): This group registers the resources your product protects, so authorization can decide about them without calling back into your application. - [roleMining](/docs/reference/api/role-mining): Role mining reads who holds which roles today and suggests simpler, narrower ways to grant the same access. - [roles](/docs/reference/api/roles): Roles are named sets of permissions for a job function, such as Editor or Approver, that bindings give to people and groups. - [root](/docs/reference/api/root): Root administrators run the platform itself: they create organizations, set plan limits, and help customers who are locked out. - [security](/docs/reference/api/security): Network blocks shut out an IP address or range during an incident, for one tenant or, set by root administrators, for the whole installation. - [serviceAccounts](/docs/reference/api/service-accounts): Service accounts are identities for machines: a deploy pipeline, a billing worker, a partner integration. - [sod](/docs/reference/api/sod): Separation-of-duties rules name roles that nobody may hold together, such as creating suppliers and approving payments to them. - [sts](/docs/reference/api/sts): The sts group issues and inspects temporary credentials, the way a cloud security token service does. - [teams](/docs/reference/api/teams): Teams are the working units inside an organization: Platform, Site Reliability, the Payments squad. - [tenants](/docs/reference/api/tenants): Tenants are the isolated organizations, projects, and other units your platform serves, arranged in a tree under one root tenant. - [trust](/docs/reference/api/trust): A trust lets one named identity, usually from another tenant, temporarily assume a role in this tenant. - [webhooks](/docs/reference/api/webhooks): Webhooks push a tenant's audit events to an HTTPS endpoint you run, signed so the endpoint can tell they came from Better IAM. - [Package exports](/docs/reference/exports): Every function, class, and constant the Better IAM packages export, what each one does, and which guide explains it. - [Types](/docs/reference/types): The core TypeScript types of Better IAM, what each one represents, and their exact fields, generated from the published declarations. - [CLI](/docs/reference/cli): The better-iam command line: what each of its 47 commands does, when to run it, and its flags. - [Error codes](/docs/reference/errors): What each of the 144 Better IAM error codes means, why it happens, and how to handle it, grouped by HTTP status. - [Glossary](/docs/reference/glossary): Plain-language definitions of the identity and access terms used throughout the Better IAM documentation. - [Packages](/docs/reference/packages): The publishable Better IAM packages with their subpath exports, runtime dependencies, and peer dependencies. - [Use the docs with AI](/docs/reference/ai): Connect AI coding assistants to these docs through MCP, or give them the whole site as Markdown with llms.txt. - [Changelog](/docs/reference/changelog): Every notable change to the Better IAM packages, newest first.