Options

This page lists every option of BetterIamOptions, the object you pass to betterIam(). Each option has its own heading with its type, default, the range enforced at startup, and a short example. Use it as a lookup table; for advice on which options a production deployment changes, read the Configuration reference.

Three options are required: database, secret, and baseURL. Every other option is optional and has a safe default. Durations are in milliseconds unless the option name ends in Seconds or Days.

A complete configuration

The examples below each show only the option they describe. A real instance always carries the three required options, as in this minimal configuration:

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!, // at least 32 characters
  baseURL: process.env.BETTER_IAM_BASE_URL!, // https, or http on localhost
});

When the CLI must load the same options, put them in better-iam.config.mjs (or .ts) as the default export. defineConfig from better-iam/server types the object, or a factory that receives { command, env, cwd }, and returns it unchanged:

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

export default defineConfig(({ env = process.env } = {}) => ({
  database: postgresAdapter({ connectionString: env.DATABASE_URL! }),
  secret: env.BETTER_IAM_SECRET!,
  baseURL: env.BETTER_IAM_BASE_URL ?? 'http://localhost:3000',
}));

In your server, call betterIam(await configOptions(config)) (also from better-iam/server) to turn a factory into options. The CLI also reads a named cli export from the same module (flag defaults for its commands); that export is CLI configuration, not a betterIam() option. See CLI.

How options are validated

betterIam() validates the whole configuration once, when it runs. A missing required option, a value outside its range, or an unknown key in a strict group (clearances) throws an IamError with code INVALID_CONFIG before the instance exists. The message names the field, for example sts.maxRoleSessionSeconds must be an integer from 900 to 43200 or vault.maxValueBytes must be an integer from 16 to 1048576. Because a misconfiguration fails at startup, it never surfaces on the first request instead.

Options that switch on an optional module (inference, ssh, verifiableCredentials, clearances, a2a) leave it off when absent. Calling one of its API methods on a deployment where it is off fails with FEATURE_DISABLED (403).

Core

The core options say where data is stored, which secret protects it, and where the deployment is reachable.

database

The storage adapter every IAM record is written to. Use postgresAdapter from better-iam/adapter-postgres, sqliteAdapter from better-iam/adapter-sqlite, libsqlAdapter from better-iam/adapter-libsql, or your own implementation of the IamStore contract. A missing value fails with INVALID_CONFIG (database is required). See Databases.

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

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  // ...secret, baseURL
});

secret

The deployment secret. It encrypts the secrets Better IAM stores (authenticator secrets, webhook secrets, pending outbox deliveries, and modules' sealed values such as vault secrets, KMS key material, SSH CA keys, and inference provider keys), keys the digests of one-time challenges, and derives the service-assertion signing key. Keep it stable across restarts and processes: replacing it outright makes enrolled factors and webhook secrets unusable. Rotate it with previousSecrets. It does not sign session JWTs, which use sts.jwt.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  secret: process.env.BETTER_IAM_SECRET!,
  // ...database, baseURL
});

previousSecrets

Deployment secrets being rotated out. Everything they sealed or signed keeps working while new values use secret. iam.rotateSecrets() re-seals stored values with the current secret, after which you remove the old ones. See Secrets and keys.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  secret: process.env.BETTER_IAM_SECRET!,
  previousSecrets: [process.env.BETTER_IAM_PREVIOUS_SECRET!],
  // ...database, baseURL
});

baseURL

The public URL people and clients reach the deployment at. It must use https:, except on the loopback hosts localhost, 127.0.0.1, and [::1] (INVALID_CONFIG: HTTPS is required outside localhost). Its origin is always a trusted origin. On HTTPS the session cookie is named __Host-better-iam.session; on plain HTTP it is better-iam.session.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  baseURL: 'https://identity.example.com',
  // ...database, secret
});

basePath

The URL path the HTTP handler answers under. It must start with /, contain only letters, digits, underscores, hyphens, and slashes, and not end with / (INVALID_CONFIG: Invalid basePath). Browser clients and framework integrations must use the same path.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  basePath: '/auth',
  // ...database, secret, baseURL
});

trustedOrigins

Additional exact origins (scheme, host, and port) allowed to call the handler from a browser. Add your application's origin when it differs from baseURL, for example https://app.example.com calling https://identity.example.com. Each entry must be an exact origin with no path (INVALID_CONFIG: Trusted origins must be exact origins). Browser requests from any other Origin are refused with UNTRUSTED_ORIGIN.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  baseURL: 'https://identity.example.com',
  trustedOrigins: ['https://app.example.com'],
  // ...database, secret
});

Authentication

authentication

How people sign in, how sessions behave, and how email and SMS leave the system. store, secret, previousSecrets, baseURL, and trustedOrigins come from the top level. The server wires onAudit and deliverWebhook itself; use events to receive events or replace the webhook transport.

DeliveryMessage carries id, tenantId, to, template, payload (string values), and, when hosts or regions are configured, signInUrl with the organization's own sign-in address.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  authentication: {
    appName: 'Acme',
    passwordlessEmail: true,
    sessionLifetimeMs: 24 * 60 * 60_000,
    passkeys: { rpID: 'example.com' },
    sendEmail: async (message) => {
      await mailer.send({ id: message.id, to: message.to, template: message.template, data: message.payload });
    },
  },
  // ...database, secret, baseURL
});

mailer stands for your own email provider client. See Email and SMS delivery and Sessions.

authentication.rateLimits

A refused attempt fails with RATE_LIMITED (429). createMemoryRateLimiter() and createStoreRateLimiter(store) from better-iam/auth are the built-in limiters; the in-memory one suits single-process deployments and tests.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  authentication: {
    rateLimits: { attempts: 5, windowMs: 10 * 60_000, ipAttempts: 200 },
  },
  // ...database, secret, baseURL
});

authentication.passwordPolicy

Passwords are hashed with Argon2id and need at least 12 characters whatever this policy says; tenant policies add their own rules (minPasswordLength, passwordHistory, and others) on top. pwnedPasswords() from better-iam/auth is a Have I Been Pwned client for isBreached that sends only a five-character SHA-1 prefix.

import { betterIam } from 'better-iam';
import { pwnedPasswords } from 'better-iam/auth';

export const iam = betterIam({
  authentication: {
    passwordPolicy: {
      isBreached: pwnedPasswords(),
      check: (password) => (/acme/i.test(password) ? 'Do not use the company name' : undefined),
    },
  },
  // ...database, secret, baseURL
});

http

Read the client IP only from a header that a proxy you control sets; never trust X-Forwarded-For otherwise. Tenant IP allowlists, IP-bound sessions, rateLimits.ipAttempts, and new-sign-in notifications all depend on a recorded IP. Invalid values fail with http.cookieSameSite must be lax or strict or http.persistentCookies must be a boolean.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  http: {
    clientInfo: (request) => ({
      ip: request.headers.get('x-real-ip') ?? undefined, // set by your own reverse proxy
      userAgent: request.headers.get('user-agent') ?? undefined,
    }),
    cookieSameSite: 'strict',
  },
  // ...database, secret, baseURL
});

See HTTP handler.

Tenancy and catalog

These options describe the shape of your product: which kinds of tenants exist, which actions and resource types policies can name, how people join, and what every new tenant starts with.

hierarchy

The kinds of tenants and which children each may have. It must define root; every allowed child must be a defined type other than root; maxDepth is 1 to 100.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  hierarchy: {
    types: {
      root: { allowedChildren: ['reseller'] },
      reseller: { allowedChildren: ['customer'] },
      customer: { allowedChildren: ['workspace'] },
      workspace: { allowedChildren: [] },
    },
    maxDepth: 6,
  },
  // ...database, secret, baseURL
});

See Tenants and identities.

permissions

A ResourceTypeDefinition has:

import { betterIam } from 'better-iam';

export const iam = betterIam({
  permissions: {
    actions: ['billing:export'],
    resourceTypes: {
      document: {
        actions: ['documents:read', 'documents:write'],
        attributes: { ownerId: 'string' },
        relations: ['viewer', 'editor'],
      },
      project: { managed: true, actions: ['projects:read', 'projects:manage'] },
    },
    identityAttributes: { department: 'string' },
  },
  // ...database, secret, baseURL
});

See The permission catalog.

onboarding

import { betterIam } from 'better-iam';

export const iam = betterIam({
  onboarding: { mode: 'linked', invitationLifetimeMs: 7 * 86_400_000 },
  // ...database, secret, baseURL
});

tenantDefaults

Both are validated at construction; errors are prefixed with tenantDefaults:. Creating past a limit fails with LIMIT_EXCEEDED. See Tenant authentication policy for every TenantAuthPolicy field.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  tenantDefaults: {
    limits: { identities: 50, serviceAccounts: 5, webhooks: 3 },
    authPolicy: { requireMfa: true, sessionLifetimeMs: 12 * 60 * 60_000 },
  },
  // ...database, secret, baseURL
});

domains

These settings serve the domains API group (verified email domains and home-realm discovery) and custom hostnames.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  domains: { recordName: '_acme-verify' },
  // ...database, secret, baseURL
});

See Enterprise onboarding.

hosts

Requests on an organization's address are pinned to that organization. A {region} pattern needs the regions option, patterns need an HTTPS baseURL outside localhost, and with passkeys configured every pattern must sit under the passkey rpID.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  hosts: {
    patterns: ['{tenant}.signin.example.com'],
    customHostnames: true,
    cnameTarget: 'custom.signin.example.com',
    signInPath: '/sign-in',
  },
  // ...database, secret, baseURL
});

See Sign-in addresses and regions.

regions

Without regions the deployment is single-region. Sign-in for an organization homed in another region answers WRONG_REGION with its sign-in URL there.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  regions: {
    current: 'eu-west-1',
    regions: {
      'eu-west-1': { baseURL: 'https://eu.identity.example.com', label: 'Europe' },
      'us-east-1': { baseURL: 'https://us.identity.example.com', label: 'United States' },
    },
  },
  // ...database, secret, baseURL
});

See Multi-region deployments.

Application callbacks

These callbacks connect authorization to your own data. They run as trusted server code during decisions.

resolveResource

Looks up an application-owned resource (a type that is not managed) in your trusted storage and returns its tenantId and attributes, so policies can check ownership and attributes. It is required for such types: without it, their checks fail with RESOURCE_RESOLVER_REQUIRED. With clearances on, it may also return a classification label, which can only raise the label IAM holds.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  resolveResource: async ({ type, id }) => {
    const document = await db.documents.find(id); // your own data access
    return { type, id, tenantId: document.tenantId, attributes: { ownerId: document.ownerId } };
  },
  // ...database, secret, baseURL
});

resolveContext

Adds trusted, server-derived keys to every policy evaluation, such as the plan a tenant pays for. Plugin context and server-owned keys take precedence over what it returns. Never pass browser input through it.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  resolveContext: async (principal) => ({ plan: await plans.forTenant(principal.tenantId) }),
  // ...database, secret, baseURL
});

plans stands for your own billing lookup.

Access workflows

accessRequests

import { betterIam } from 'better-iam';

export const iam = betterIam({
  accessRequests: { lifetimeMs: 3 * 86_400_000, maxDurationSeconds: 30 * 86_400 },
  // ...database, secret, baseURL
});

See Temporary access.

accessUsage

Records which actions each identity actually uses, so roleMining.usage and roleMining.rightSize can point out unused bindings and never-used grants. Usage is buffered in memory and written in batches; call iam.flushAccessUsage() before the process exits.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  accessUsage: { flushIntervalMs: 30_000 },
  // ...database, secret, baseURL
});

See Usage and role mining.

Events, audit, and telemetry

events

A WebhookDelivery carries id, tenantId, webhookId, url, event, body, and headers.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  events: {
    onEvent: async (event) => {
      await siem.send(event); // your own sink
    },
    webhookTimeoutMs: 5_000,
  },
  // ...database, secret, baseURL
});

See Events and Webhooks.

auditArchive

Archiving runs when you call iam.archiveAudit(). While auditArchive is set, iam.pruneAudit deletes only events already archived. createJsonlAuditArchive from better-iam/server is a file-based sink.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  auditArchive: {
    write: async (batch) => {
      const key = `${batch.tenantId}/${batch.fromSequence}-${batch.toSequence}.json`;
      await bucket.putIfAbsent(key, JSON.stringify(batch)); // your object storage
    },
    batchSize: 5_000,
  },
  // ...database, secret, baseURL
});

See Continuous audit archiving.

observability

MetricsOptions:

An IamSpan has kind, name, tenantId, outcome (ok, denied, or error), code, status, requestId, and durationMs.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  observability: {
    // histogram stands for an instrument from your own metrics library
    onSpan: (span) => histogram.observe({ kind: span.kind, outcome: span.outcome }, span.durationMs),
    metrics: { bearerToken: process.env.METRICS_TOKEN! },
  },
  // ...database, secret, baseURL
});

See Observability.

Extensions and protocols

plugins

Plugins add actions, platform resource types, POST endpoints under {basePath}/plugins/{pluginId}/..., operation hooks, policy context, migrations, and purge handlers. Construction checks for unique ids, registered endpoint actions, and unique, well-formed endpoint paths with a validator and a handler. createProjectsPlugin() from better-iam/projects is the reference plugin.

import { betterIam } from 'better-iam';
import { createProjectsPlugin } from 'better-iam/projects';

export const iam = betterIam({
  plugins: [createProjectsPlugin()],
  // ...database, secret, baseURL
});

See Adapters and plugins.

protocols

Raw request handlers consulted before the IAM routes. A ProtocolMount has an optional handle(request: Request): Promise<Response | undefined> and an optional nodeHandler(req, res); returning undefined (or false) passes the request on. Most deployments attach the OAuth, SAML, and SCIM services with iam.useProtocol(service) after construction instead of listing them here.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  protocols: [
    {
      handle: async (request) =>
        new URL(request.url).pathname === '/.well-known/acme-status'
          ? Response.json({ ok: true })
          : undefined,
    },
  ],
  // ...database, secret, baseURL
});

See Protocol mounts.

Temporary credentials

sts

import { betterIam } from 'better-iam';

export const iam = betterIam({
  sts: { maxRoleSessionSeconds: 7200, maxSessionTokensPerIdentity: 20 },
  // ...database, secret, baseURL
});

See Tokens and temporary credentials.

sts.jwt

These keys are separate from secret and are never shared with the OAuth provider. The public keys are served at GET {basePath}/.well-known/jwks.json.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  sts: {
    jwt: {
      signingKeys: [JSON.parse(process.env.SESSION_JWT_KEY!)], // { kty: 'OKP', crv: 'Ed25519', alg: 'EdDSA', kid, x, d }
      audiences: ['https://api.example.com'],
      maxLifetimeSeconds: 900,
    },
  },
  // ...database, secret, baseURL
});

sts.webIdentity

import { betterIam } from 'better-iam';

export const iam = betterIam({
  sts: {
    webIdentity: {
      enabled: true,
      allowedIssuers: ['https://token.actions.githubusercontent.com'],
    },
  },
  // ...database, secret, baseURL
});

Optional modules

Each option in this section turns on, or tunes, one feature module. inference, a2a, ssh, verifiableCredentials, and clearances are off until set; while off, their methods answer FEATURE_DISABLED. billing, vault, and signals are always available; their options tune or extend them.

inference

Inference access control for AI models: the model resource type and the inference:invoke action, the inference API group (providers with sealed keys, models, budgets, usage), and iam.inference (checks, metering, and the gateway). true enables it with defaults.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  inference: { usageRetentionDays: 30 },
  // ...database, secret, baseURL
});

See Model access and budgets.

a2a

Keys for IAM-attested Agent2Agent cards (agents.signCard) and delegation tokens; their public half is published by iam.a2a.jwks(). Delegation tokens need this option.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  a2a: {
    signingKeys: [JSON.parse(process.env.A2A_CARD_KEY!)],
    jwksUrl: 'https://identity.example.com/.well-known/a2a-jwks.json',
  },
  // ...database, secret, baseURL
});

See Agent-to-agent.

billing

import { betterIam } from 'better-iam';

export const iam = betterIam({
  billing: {
    currency: 'EUR',
    timeZone: 'Europe/Berlin',
    issuer: { name: 'Acme GmbH', email: 'billing@acme.example' },
    autoFinalize: false,
  },
  // ...database, secret, baseURL
});

See Billing and spend.

ssh

The SSH certificate authority: short-lived OpenSSH user certificates for the hosts and logins policies allow, host certificates, and revocation lists (ssh API group, iam.ssh). true enables it with defaults.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  ssh: { maxUserCertificateMs: 8 * 60 * 60_000 },
  // ...database, secret, baseURL
});

See SSH access.

verifiableCredentials

Every tenant issues SD-JWT verifiable credentials to wallets over OpenID4VCI and verifies presentations (verifiableCredentials API group, the {basePath}/vc/{tenantId} issuer endpoints, iam.verifiableCredentials). true enables it with defaults.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  verifiableCredentials: { maxLifetimeMs: 90 * 86_400_000 },
  // ...database, secret, baseURL
});

See Verifiable credentials.

clearances

Security clearances and mandatory access control: tenants define a classification scheme, officers adjudicate clearances and read people into compartments, and resources carry classification labels that every party of a decision must dominate (clearances API group, iam.clearances). Its presence enables the module, and it must be an object: clearances: true fails with clearances must be an object, and unknown keys fail too.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  clearances: {},
  // ...database, secret, baseURL
});

See Security clearances.

vault

A rotator receives { tenantId, name, version, value, fields?, previous?, previousFields?, tags } and must be idempotent: a failed rotation is retried with the same value.

import { betterIam } from 'better-iam';

export const iam = betterIam({
  vault: {
    rotators: {
      postgres: {
        rotate: async ({ value, tags }) => {
          await databaseAdmin.setPassword(tags.role, value); // your own code that applies the new value
        },
      },
    },
  },
  // ...database, secret, baseURL
});

See Secrets vault.

signals

These settings configure the Shared Signals receiver (signals API group, iam.signals).

import { betterIam } from 'better-iam';

export const iam = betterIam({
  signals: { pushPath: '/ssf/push' },
  // ...database, secret, baseURL
});

See Shared Signals receiver.

Errors

Startup validation cannot judge everything, such as a placeholder-like secret or a missing email transport. better-iam doctor checks those; see Doctor.

Related