Migration guides

Moving to Better IAM from a hosted identity provider or an authentication library is mostly a data move: the people, the organizations they belong to, the roles they hold, and the SSO and directory connections their companies use. This page is the general plan that every provider-specific guide follows. It covers what carries over and what cannot, the bulk import APIs, how imported people sign in without their old password, how to run both systems side by side while you switch, and how to roll back.

The short version:

• People, organizations, roles, groups, and role assignments move through the API, 100 people per transaction.
• Verified email status and links to social or enterprise accounts move with each person, so people who signed in through a provider keep doing so. Password hashes, authenticator secrets, passkeys, and sessions do not move: everyone else signs in once with a magic link or a reset link.
• SSO and SCIM connections are recreated, and each customer's IT team points its identity provider at the new connection.
• You switch over one organization at a time while the old system keeps running, so rolling back means pointing that organization back.

Pick a guide

What carries over

Map the concepts

Hosted providers use similar words for different things. The provider guides have a full table for each provider; these are the mappings that change how you plan.

Passwords, factors, and sessions

Password hashes

Better IAM hashes passwords with Argon2id and sets them only from plaintext. No API accepts a precomputed hash, and there is no hook that checks a legacy hash at first sign-in. Exporting bcrypt, scrypt, PBKDF2, or any other hashes from the old provider therefore gains nothing: they cannot be loaded. See Hashing.

People you import without a password are active and have no password. Their email address is unverified unless you pass emailVerified: true, which you should do only when the old system says the address is verified. Choose how each group of people signs in:

identities.requestPasswordReset needs iam:identities:update and recent authentication: a session signed in within recentAuthenticationMs (five minutes by default), or an API key created within that window. It queues the password-reset email whether or not the address is verified.

Capture passwords at first sign-in

If the old provider can still verify a password from your server, you can keep people's passwords without ever seeing a hash: when someone signs in during the dual run and has no Better IAM account yet, check the password with the old provider, then create the identity with that password. This is code you write in your application, not a Better IAM feature, and it only works for people who have not been imported yet, because no API sets a password on an existing identity.

import { IamError } from 'better-iam';
import { iam } from '@/lib/iam';
import { verifyWithOldProvider } from '@/lib/old-provider'; // your code: returns { name } or null

const migration = { token: process.env.BETTER_IAM_MIGRATION_TOKEN! }; // API key with iam:identities:create and :read
const tenantId = process.env.APP_TENANT_ID!;

export async function POST(request: Request) {
  const { email, password } = (await request.json()) as { email: string; password: string };
  const normalized = email.trim().toLowerCase();
  const matches = await iam.api.identities.list(migration, { tenantId, query: normalized, limit: 20 });
  if (!matches.some((identity) => identity.email === normalized)) {
    const legacy = await verifyWithOldProvider(normalized, password);
    if (legacy) {
      try {
        await iam.api.identities.create(migration, { tenantId, email: normalized, name: legacy.name, password });
      } catch (error) {
        // Too short for the password policy, found in a breach list, or created concurrently:
        // leave the person for the bulk import, where they sign in with a magic link instead.
        if (!(error instanceof IamError)) throw error;
      }
    }
  }
  return new Response(null, { status: 204 }); // same answer either way
}

Your sign-in form posts to this route first, then signs in with Better IAM as usual (auth.signIn). Keep these points in mind:

• Passwords must satisfy the Better IAM password policy (at least 12 characters, plus any tenant rules), so shorter legacy passwords are refused with WEAK_PASSWORD and those people use the fallback.
• The new identity's email is unverified unless you also pass emailVerified: true (only when the old provider reports the address verified). With authentication.requireEmailVerification on, an unverified person's sign-in fails with EMAIL_UNVERIFIED until they follow the link from auth.requestEmailVerification.
• Rate-limit the route like any sign-in endpoint, and keep the old provider running until the route is removed.

Bridge sign-in through the old provider

If the old provider can act as an OpenID Connect provider for other applications (Auth0 can, for example), add it as an upstream kind: 'oidc' connection during the dual run. People sign in at the old provider with the password and factors they already have; on their first sign-in Better IAM creates their account with a verified email and links it to the old provider's subject. The ID token must say email_verified: true; otherwise that first sign-in fails with VERIFIED_EMAIL_REQUIRED.

import { createOAuthLogin } from 'better-iam/oauth';
import { iam } from './iam';

export const login = createOAuthLogin({
  ...iam.protocolHost,
  connections: [
    {
      id: 'legacy',
      tenantId: process.env.APP_TENANT_ID!,
      kind: 'oidc',
      issuer: process.env.LEGACY_ISSUER!, // the old provider's issuer URL, as in its discovery document
      clientId: process.env.LEGACY_CLIENT_ID!,
      clientSecret: process.env.LEGACY_CLIENT_SECRET!,
      redirectUri: 'https://app.example.com/oauth/legacy/callback',
    },
  ],
});
iam.useProtocol(login);

People you import can use the bridge too: give each one a providers entry with providerId: 'legacy', the old provider's issuer, and the sub its ID tokens carry for that person (usually the old user ID), as in Social and SSO accounts. Without that entry, an imported person's first sign-in through the bridge fails with ACCOUNT_LINK_REQUIRED. When you retire the old provider, remove the connection; its accounts stay, have no password, and sign in with a magic link or a reset link from then on.

Factors, passkeys, and sessions

TOTP secrets, SMS factors, recovery codes, and passkeys stay with the system that issued them; passkeys are also bound to the old provider's relying-party domain. People enroll again: if a tenant's policy sets requireMfa, people without a factor enroll at their next sign-in (MFA). Sessions and refresh tokens do not carry over either, so everyone signs in once after the switch.

Social and SSO accounts

Better IAM finds the account for a federated sign-in by its link: the connection, the provider's issuer, and the person's subject at the provider. Create those links at import with providers on each createMany entry (up to 10 per person, one per connection), or later with identities.linkProvider. The person's first sign-in through a linked connection then signs in to the imported account, with its roles, instead of failing with ACCOUNT_LINK_REQUIRED.

Old systems record these under their own names, for example a provider called google-oauth2 or oauth_google. Map each one to the connection you created for that provider in the person's tenant:

type LegacyAccount = { provider: string; subject: string }; // from the old system's export

/** The old system's provider name -> the Better IAM connection that replaces it, and that provider's issuer. */
const connections: Record<string, { providerId: string; issuer: string }> = {
  google: { providerId: 'app-google', issuer: 'https://accounts.google.com' },
  github: { providerId: 'app-github', issuer: 'https://github.com' },
};

export function providerLinks(accounts: LegacyAccount[]) {
  return accounts.flatMap(({ provider, subject }) => {
    const connection = connections[provider];
    return connection ? [{ ...connection, subject }] : []; // other providers: magic link instead
  });
}

A subject must be the provider's stable user ID exactly as the connection reports it at sign-in; an email address or a display name never matches. An external account links to one identity only, and each identity has at most one link per connection: a second link fails with ACCOUNT_LINK_CONFLICT. identities.linkProvider needs iam:identities:update and recent authentication, and only another owner or a root principal links an owner; identities.listProviders and identities.unlinkProvider show and remove links.

Bulk import APIs

Routes are relative to the handler's basePath (/api/iam by default). From a terminal, better-iam api identities.createMany --data @batch.json --tenant TENANT_ID calls the same method with the same permission checks; see the CLI.

Plan the migration

The provider guides fill in these steps with each provider's export format. The code here assumes an instance module iam.ts that exports iam, and a credential for a root administrator or for the organization's owner.

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

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: process.env.BETTER_IAM_BASE_URL!,
  authentication: {
    sendEmail, // magic links, reset links, invitations
    passwordlessEmail: true, // imported people sign in with a magic link the first time
  },
  permissions: {
    identityAttributes: { legacyId: 'string' },
    resourceTypes: {
      invoice: { actions: ['invoices:read', 'invoices:create'] },
    },
  },
});

import { writeFile } from 'node:fs/promises';
import { iam } from '../iam';

const credential = { token: process.env.BETTER_IAM_TOKEN! }; // a root administrator's session
const rootTenantId = process.env.ROOT_TENANT_ID!;
type Organization = {
  legacyId: string;
  name: string;
  ownerEmail: string;
  ownerName: string;
  ownerEmailVerified: boolean; // as the old system reports it
};
const organizations = JSON.parse(process.env.ORGANIZATIONS_JSON ?? '[]') as Organization[];

const tenantIds: Record<string, string> = {};
for (const organization of organizations) {
  const { tenant } = await iam.api.tenants.create(credential, {
    parentId: rootTenantId,
    type: 'organization',
    name: organization.name,
    ownerEmail: organization.ownerEmail,
    activate: true, // active now, owner created without an invitation
    ownerName: organization.ownerName,
    ownerEmailVerified: organization.ownerEmailVerified,
  });
  tenantIds[organization.legacyId] = tenant.id;
}
await writeFile('tenant-map.json', JSON.stringify(tenantIds, null, 2));

import { iam } from '../iam';

const credential = { token: process.env.BETTER_IAM_TOKEN! };

export const rolesDocument = {
  version: 1,
  roles: [
    { name: 'Admin', permissions: ['invoices:read', 'invoices:create'] },
    { name: 'Member', permissions: ['invoices:read'] },
  ],
};

export async function applyRoles(tenantId: string) {
  const plan = await iam.api.config.plan(credential, { tenantId, config: rolesDocument });
  console.log(tenantId, plan);
  await iam.api.config.apply(credential, { tenantId, config: rolesDocument });
}

import { readFile, writeFile } from 'node:fs/promises';
import { iam } from '../iam';

type Person = {
  legacyId: string;
  email: string;
  emailVerified: boolean; // as the old system reports it
  name: string;
  roles: string[];
  providers: Array<{ providerId: string; issuer: string; subject: string }>; // see providerLinks()
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };

async function existingEmails(tenantId: string): Promise<Set<string>> {
  const emails = new Set<string>();
  for (let offset = 0; ; offset += 1000) {
    const page = await iam.api.identities.list(credential, { tenantId, kind: 'user', limit: 1000, offset });
    for (const identity of page) if (identity.email) emails.add(identity.email);
    if (page.length < 1000) return emails;
  }
}

export async function importPeople(tenantId: string, people: Person[]): Promise<Record<string, string>> {
  const roleIds = new Map(
    (await iam.api.roles.list(credential, { tenantId })).map((role) => [role.name, role.id]),
  );
  const seen = await existingEmails(tenantId);
  const pending = people.filter((person) => {
    const email = person.email.trim().toLowerCase();
    if (seen.has(email)) return false; // already imported, or the tenant's owner
    seen.add(email); // also drops duplicates inside the export
    return true;
  });

  const idMap: Record<string, string> = {};
  for (let start = 0; start < pending.length; start += 100) {
    const batch = pending.slice(start, start + 100);
    const { identities } = await iam.api.identities.createMany(credential, {
      tenantId,
      identities: batch.map((person) => ({
        email: person.email,
        name: person.name || person.email,
        emailVerified: person.emailVerified,
        providers: person.providers,
        attributes: { legacyId: person.legacyId },
        roleIds: person.roles.flatMap((name) => roleIds.get(name) ?? []),
      })),
    });
    // Results come back in the order sent: identities[i] replaces batch[i].
    batch.forEach((person, i) => (idMap[person.legacyId] = identities[i]!.id));
  }
  return idMap;
}

const tenantId = process.env.TENANT_ID!;
const people = JSON.parse(await readFile(process.argv[2] ?? 'people.json', 'utf8')) as Person[];
const idMap = await importPeople(tenantId, people);
await writeFile(`id-map-${tenantId}.json`, JSON.stringify(idMap, null, 2));

Cut over with a dual run

Switch organizations one at a time while the old system keeps serving everyone else. Your application decides per organization which system signs people in, for example with a flag on your own organization record.

During the dual run, make Better IAM the one place you change roles for organizations that have switched, and the old system the one place for those that have not. Changing both invites drift.

Roll back

Rolling back is cheap as long as the old system still holds everyone and nobody depends on changes made only in Better IAM:

• Point the organization back. Flip your per-organization flag. Its people sign in to the old system again, where their passwords, factors, and links still exist.
• Know what does not flow back. Accounts created in Better IAM after the switch, role changes made there, and passwords set there do not exist in the old system. No API returns a password hash, so people who joined or changed their password after the switch reset it in the old system.
• Keep the old tenant intact. Do not delete the old provider's data or connections until the rollback window ends. SSO keeps working there as long as the customer's identity provider still has the old application.
• Start the import again. To discard an import, restore the snapshot you took before it into an empty database with better-iam store-import, or delete the tenants you created with tenants.setStatus (status: 'deleted'). Deleted tenants are purged after the retention window by better-iam purge.

Errors

Next steps