Migrate from WorkOS

What you'll keep, what you'll lose, what you'll gain

• Keep: SSO connections (SAML / OIDC), SCIM directories, organization names and domains, AuthKit users, audit-style identity records.
• Lose: WorkOS sessions (users re-authenticate on next visit), AuthKit passwords (Authio is passwordless), MFA secrets (the enrolled flag is preserved; users re-enroll TOTP if applicable).
• Gain: One Authio user per email, not per (email, org). Passkeys. Magic links. The risk engine. The audit stream. Multi-tenant pricing without per-org-per-MAU.

The multi-org merge

WorkOS assigns a fresh user_id every time the same email joins a new organization. The same person across three of your customers ends up as three separate WorkOS user records with three different passwords, three different MFA enrollments, and zero shared identity surface. That's the problem that motivated Authio.

Authio's WorkOS importer detects users with the same email across multiple WorkOS orgs and merges them into a single Authio user with N memberships. You'll see the merge count called out in the importer summary:

  warning: workos: merged 47 duplicate-email users into 23 Authio users
           with multi-org memberships

SSO connections — directly mapped

Every WorkOS connection (SAML or OIDC) becomes an Authio sso_connection record on the corresponding Authio organization. The IdP-side metadata (entity ID, signing cert, ACS URL) is recorded in the import plan as a warning so you know exactly which ones to provision in Authio's SSO section. The IdP-side admin has to point the existing connection at Authio's new ACS URL, but the Authio-side org and connection record are ready and waiting.

Directory Sync (SCIM) — directly mapped

Each WorkOS directory becomes an Authio scim_directory on the same org. The Authio side generates a fresh bearer token; reconfigure your IdP's SCIM connector to point at Authio's SCIM endpoint with the new token, and provisioning resumes.

Sessions

Old WorkOS sessions are dropped on cutover. Users sign in via passkey or magic link on next visit. There is no “keep the old session warm” option, and we think this is a feature: it gives every user a fresh, attested credential at the moment of migration.

Rollback plan

Run Authio in parallel for as long as you need. The importer is idempotent — re-run with the latest WorkOS export every night during a phased cutover. While WorkOS is still authoritative, Authio is a read-only mirror; flip your app's login URL only when you're ready.

1. Phase 0: import nightly, no app changes. WorkOS remains primary.
2. Phase 1: route a single test org to Authio's hosted UI.
3. Phase 2: route 10% of orgs.
4. Phase 3: flip the remaining 90% and decommission WorkOS.

Step-by-step: CLI

# 1) Install the CLI
go install github.com/tcast/authio_cli/cmd/authio@latest
authio login

# 2) Assemble a WorkOS bundle.
H="Authorization: Bearer $WORKOS_API_KEY"
fetch() { curl -s "https://api.workos.com/$1?limit=100" -H "$H" | jq '.data'; }
jq -n --argjson users  "$(fetch users)" \
      --argjson orgs   "$(fetch organizations)" \
      --argjson mems   "$(fetch organization_memberships)" \
      --argjson sso    "$(fetch sso/connections)" \
      --argjson dirs   "$(fetch directories)" \
  '{users: $users, organizations: $orgs, organization_memberships: $mems,
    sso_connections: $sso, directories: $dirs}' > workos.json

# 3) Dry-run first.
authio import workos --input ./workos.json --dry-run | jq '.stats'

# 4) Apply.
authio import workos --input ./workos.json

Step-by-step: dashboard wizard

1. Open app.authio.com/migrate/workos.
2. Follow the bundle-assembly snippet in Step 1.
3. Upload workos.json in Step 2; review the plan.
4. Confirm in Step 3 — the per-record progress log streams below.
5. Step 4 shows merge counts and warnings. Send the migration email blast from the post-migration checklist.

Live import (paste an API token)

The dashboard wizard's Connect with API token tab pulls users, orgs, memberships, SSO connections, and SCIM directories directly from api.workos.com.

1. WorkOS dashboard → API Keys → create a sk_live_… token with read access to users, organizations, memberships, sso, directories.
2. Paste it into the wizard. The probe call validates by hitting /sso/connections?limit=1.
3. Start the job. Watch the merge-by-email counter — that's the marquee moment for WorkOS migrations.

Live import via the CLI

authio import workos \
  --live-token "$WORKOS_API_KEY" \
  --dry-run

Post-migration checklist

• Send migration emails. Authio surfaces the queue at /users?migration_pending_email=true.
• Verify a sample login as a known user. Pick someone in two+ orgs to verify the merge worked.
• Re-create each SSO connection on Authio's side. The plan listed the IdP-side metadata for each.
• Re-create each SCIM directory and rotate the connector's bearer token.
• Decommission WorkOS only after one billing cycle of clean Authio operation.