Migrate from WorkOS

Step-by-step guide to migrating users, organisations, and connections from WorkOS to Wocha

This guide covers migrating from WorkOS User Management, SSO, and Directory Sync to Wocha.

Prerequisites

Requirement	Details
WorkOS API key	`sk_live_...` or `sk_test_...` from the WorkOS Dashboard
Required scopes	`user_management:read`, `sso:read`, `dsync:read`
Wocha tenant	`npx @wocha/cli init --cloud`
Management API key	`WOCHA_MANAGEMENT_API_KEY` with `users:write`, `organisations:write`, `connections:write`

Concept mapping

WorkOS	Wocha
User Management user	User
Organization	Organisation
Organization membership	Organisation member + SpiceDB relation
SSO Connection	Enterprise connection
Directory Sync directory	SCIM connection
Role (RBAC)	Organisation role / SpiceDB permission

Data mapping

WorkOS field	Wocha field
`user.id`	`metadata_admin.workos_id`
`user.email`	`traits.email`
`user.first_name` + `last_name`	`traits.name`
`organization.id`	`metadata.workos_org_id` on organisation
`organization.name`	`display_name` / `slug`
SSO `connection.id`	Enterprise connection (manual OAuth/SAML config)
Directory Sync `directory.id`	SCIM connection

Step 1 — Dry run

Always preview the migration before importing:

export WOCHA_MANAGEMENT_API_KEY=wocha_mgmt_...
export WOCHA_TENANT=your-tenant
 
wocha migrate workos --dry-run

The dry run reports:

Number of users, organisations, and connections to migrate
Duplicate emails or invalid data
SSO and SCIM connections that need manual configuration in the Wocha Console

A JSON migration plan is written to wocha-migrate-plan-workos-*.json.

Step 2 — Import users

wocha migrate workos

The CLI prompts for your WorkOS API key and imports users via the Customer API. Organisation and connection records are mapped in metadata; configure SSO and SCIM in the Console after user import.

Step 3 — Map organisations and roles

WorkOS organisations are mapped to Wocha organisations by slug. After user import, verify membership:

import { WochaClient } from "@wocha/sdk";
 
const wocha = new WochaClient({ tenant: process.env.WOCHA_TENANT!, apiKey: process.env.WOCHA_API_KEY! });
 
for (const org of workosOrgs) {
  const created = await wocha.organisations.create({
    slug: org.name.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
    display_name: org.name,
    metadata: { workos_org_id: org.id },
  });
 
  // Add members and assign roles via SpiceDB permissions
  await wocha.organisations.addMember(created.id, {
    identity_id: greetUserId,
    role: "member",
  });
}

Step 4 — Configure enterprise connections

WorkOS SSO connections cannot be fully auto-imported (SAML certificates and IdP metadata are tenant-specific). Use the Wocha Console or Customer API:

Connections → Enterprise — recreate SAML/OIDC connections
Connections → SCIM — configure Directory Sync endpoints

Handling passwords

WorkOS User Management does not export password hashes. Options:

Magic link re-registration — wocha.users.sendRecovery(userId) after import
SSO-only — if users authenticate via WorkOS SSO, configure enterprise connections first
Parallel auth — run WorkOS and Wocha side by side during transition

Step 5 — Validate migration

wocha migrate workos --validate

Validation checks:

All source users exist in Wocha (matched by email)
Organisation counts align
Social and enterprise connections are configured

Post-migration checklist

All users imported (--validate passes)
Organisations created with correct slugs
SSO connections configured and tested
SCIM directory sync reconnected
Application SDK updated to Wocha
Webhooks remapped to Wocha event types
Recovery emails sent to password-based users

Rollback considerations

Keep WorkOS active until validation passes
User metadata preserves workos_id for cross-reference
Deleting imported Wocha users does not affect WorkOS — safe to re-run import (duplicates are skipped)
SSO cutover requires DNS and IdP metadata updates — plan a maintenance window

Migrate from WorkOS

On this page