Configuration reference

Everything a Better IAM instance does is decided by the options object you pass to betterIam(). Most options have safe defaults, so a development instance needs only a database, a secret, and a URL. Production deployments usually adjust a handful more: delivery callbacks, the client-IP hook, session lifetimes, and metrics.

The configuration is validated once, when betterIam() runs. Anything out of range throws an IamError with code INVALID_CONFIG before the instance exists, so a misconfigured deployment fails at startup instead of on the first request. Durations are in milliseconds unless the name ends in Seconds or Days.

betterIam({
  database, secret, previousSecrets, baseURL, basePath, trustedOrigins, // core
  authentication, http,                                                  // sign-in and transport
  hierarchy, permissions, onboarding, tenantDefaults, domains,           // tenancy and catalog
  hosts, regions,                                                        // sign-in addresses and regions
  inference, a2a, billing,                                               // AI models, agent cards, spend
  resolveResource, resolveContext,                                       // application integration
  accessRequests, accessUsage,                                           // access workflows
  events, auditArchive, observability,                                   // events, audit, telemetry
  plugins, protocols, sts,                                               // extensions and credentials
});

Core

The core options tell the instance where its data lives (the storage adapter), which secret protects it, and where it is reachable. Every deployment sets the first four.

Authentication

authentication configures how people sign in, how sessions behave, and how messages reach them. It accepts every AuthOptions field except store, secret, previousSecrets, baseURL, and trustedOrigins, which come from the top level. Its onAudit and deliverWebhook hooks are wired by the server itself, so use events.onEvent and events.deliverWebhook instead.

Sign-in methods and delivery

These options decide which sign-in methods exist at all, and how email and SMS leave the system through the outbox. Tenants can restrict methods further with their own policy, but never enable one the deployment turned off.

Sessions, devices, and notifications

These options bound how long a sign-in lasts and what people are told about activity on their account. Tenant policies can shorten the lifetimes, never extend them.

Rate limits

authentication.rateLimits bounds how fast anyone can guess credentials. Counters are durable and shared by every instance through the database by default. A refusal is RATE_LIMITED (429) with retryAfterMs in the body and a Retry-After header.

Password policy

authentication.passwordPolicy screens every password the deployment accepts, wherever it is set. Passwords always use Argon2id and need at least 12 characters; tenant policies add their own rules on top of these.

HTTP

The http options shape how the handler treats the browser: which client details it records and how its cookies behave.

Tenancy and catalog

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

Application integration

These two callbacks connect authorization to your own data. They run as trusted server code on every decision that needs them.

Access workflows

These options tune self-service access requests and the usage tracking behind role mining.

Events and audit

These options decide where audit events go after commit: to your code, to webhooks, and to an independent archive of the audit chain.

Observability

These options expose timing and outcomes of everything the instance does. See Observability for span fields and metric names.

Extensions and protocols

These options add code to the instance: plugins that extend the API, and raw protocol handlers.

AI models, agent cards, and billing

These options turn on and tune the features for AI agents and spend tracking. Each has its own guide with the full settings.

Temporary credentials

sts controls temporary credentials: how long role sessions and session tokens may last, whether session tokens can be signed JWTs that services verify offline, and whether workloads (CI, Kubernetes, cloud functions) may exchange their own OIDC tokens for role sessions. Invalid values throw INVALID_CONFIG naming the field, such as sts.maxRoleSessionSeconds must be an integer from 900 to 43200.

Session JWT signing

sts.jwt holds the keys that sign session JWTs and the rotation window for retired keys.

Web-identity federation

sts.webIdentity governs the OIDC token exchange, including the safety limits on fetching each provider's keys.

Validation rules at a glance

Construction fails with INVALID_CONFIG when:

• database is missing, or secret is shorter than 32 characters;
• previousSecrets lists more than five values, repeats one, includes one shorter than 32 characters, or includes secret;
• baseURL is not HTTPS outside localhost, 127.0.0.1, and [::1], or basePath is malformed or ends with a slash;
• a trusted origin is not an exact origin, or the passkey RP ID does not match every trusted origin;
• requireEmailVerification or passwordlessEmail is on without sendEmail, passwordlessSms is on without sendSms, or failedSignInAlerts is set without sendEmail;
• a session, idle, recent-authentication, trusted-device, rate-limit, delivery-attempt, access-request, webhook-timeout, archive, or sts value is outside the ranges above;
• http.cookieSameSite is not lax or strict, or http.persistentCookies is not a boolean;
• the hierarchy has no root, names an undefined or root child, or sets maxDepth outside 1 to 100;
• tenantDefaults fails tenant limit or authentication policy validation;
• plugins repeat an id, or an endpoint uses an unregistered action, a method other than POST, a duplicate or malformed path, or lacks a validator or handler.

Startup validation cannot judge everything. doctor catches the rest: a placeholder-like secret, a short metrics token, or no email transport. See Doctor.

Next steps