Tenancy and limits

These recipes cover running Better IAM as the identity layer of a multi-tenant SaaS product: enforcing what each plan includes, bringing whole teams in at once, and choosing where the data lives. credential is the caller's credential ({ token } or { headers }).

Plan limits and usage

The problem: your pricing plans include a number of seats, webhooks, or roles, and the limit has to hold on every path that creates a record, not only in your own signup form.

The solution: set plan limits on the tenant with tenants.setLimits. They are checked inside every creation transaction, and tenants.usage reports the current counts for dashboards and billing.

await iam.api.tenants.setLimits(rootCredential, {
  tenantId,
  limits: { identities: 25, webhooks: 5 },
});
const usage = await iam.api.tenants.usage(credential, { tenantId });
// usage: identities, mfaEnrolled, serviceAccounts, groups, roles, policies, resources,
// relationships, webhooks, activeSessions, and the limits

Creation past a limit fails with LIMIT_EXCEEDED on every path, including invitation acceptance, SCIM, and bulk creation.

• Only root administrators set limits, and each change is audited as tenant:limits. limits: null removes them.
• Limits cover members (identities), serviceAccounts, groups, roles, policies, registered resources, and webhooks. Deleted tombstones do not count.
• The check also covers self-registration and federation, and invitations accepted after the limit was reached.
• tenants.usage reports the current counts, how many members enrolled MFA, the active sessions, and the limits, for dashboards and metering.
• To give every new organization a default plan, set tenantDefaults.limits in the configuration. It is stamped on every tenant that tenants.create creates.

See Tenants and identities.

Bulk onboarding and directory attributes

The problem: a new customer arrives with a spreadsheet of fifty people, or with an identity provider that should keep their directory in sync. Your policies need facts about those people, such as each person's department.

The solution: create people in bulk, with attributes and roles, using identities.createMany. For a directory that changes, let SCIM provision people and map the enterprise directory into the same declared attributes with mapAttributes.

await iam.api.identities.createMany(credential, {
  tenantId,
  identities: rows.map((row) => ({
    email: row.email,
    name: row.name,
    attributes: { department: row.department },
    roleIds: [editor.id],
  })),
});

import { createScimService } from 'better-iam/scim';

// SCIM: map the enterprise extension to declared identity attributes.
const scim = createScimService({
  ...iam.protocolHost,
  mapAttributes: ({ title, enterprise }) => ({
    ...(title ? { title } : {}),
    ...(typeof enterprise?.department === 'string' ? { department: enterprise.department } : {}),
  }),
});
iam.useProtocol(scim);

• identities.createMany creates up to 100 identities in one transaction, applying attributes, roles, and groups under the caller's authority. Plan limits and password rules apply as for single creation.
• Attributes must be declared in permissions.identityAttributes. They reach policies as principal.department and so on.
• SCIM stores the enterprise user extension (department, costCenter, manager, and the rest) as provisioned. mapAttributes turns it into declared attributes, which the host validates, so the directory drives policy conditions. The extension's manager also becomes the person's manager for approvals.

See SCIM and Tenants and identities.

Move people over from another system

The problem: you are replacing an existing login system, either your own users table or a hosted provider, and the people in it must keep their organization and their access without signing up again.

The solution: recreate the organizations first, import people in batches with the old user ID kept as an attribute, then let each group of people in the way that matches how they sign in today. Credentials themselves do not move: no API accepts a password hash, and passkeys and authenticator apps are registered with the system that issued them. What moves is who people are, where they belong, and what they may do.

export const iam = betterIam({
  // ...
  permissions: { identityAttributes: { legacyId: 'string' } },
});

for (let start = 0; start < users.length; start += 100) {
  const batch = users.slice(start, start + 100);
  const { identities } = await iam.api.identities.createMany(credential, {
    tenantId,
    identities: batch.map((user) => ({
      email: user.email,
      name: user.name,
      attributes: { legacyId: user.id },
      roleIds: [user.isAdmin ? adminRoleId : memberRoleId],
    })),
  });
  // identities[i] replaces batch[i]: keep the mapping for your own tables.
  await saveMapping(batch.map((user, i) => [user.id, identities[i]!.id]));
}

See Tenants and identities and sign-in methods.

Store data in libSQL or Turso

The problem: you want SQLite's simplicity, but the database must be reachable from several regions or serverless instances, or you want a local replica close to the application.

The solution: use the libSQL storage adapter. One set of options covers local files, encrypted files, embedded replicas, and remote Turso or sqld databases.

import { betterIam } from 'better-iam';
import { libsqlAdapter } from 'better-iam/adapter-libsql';

const iam = betterIam({
  // ...
  database: libsqlAdapter({
    url: 'libsql://name-org.turso.io',
    authToken: process.env.TURSO_AUTH_TOKEN,
  }),
});

• url also accepts file:./iam.db, a plain path, :memory:, and https: or wss: URLs. syncUrl with a local file makes an embedded replica, and encryptionKey encrypts a local file.
• Remote servers queue write transactions themselves. Locally, transactions run one at a time and take the writer lock before any read.
• Local libSQL writes cost more than the SQLite adapter's, because @libsql/client compiles each statement on every call.

See Storage adapters for every option, and for moving an existing deployment with store-copy.

Next steps