Use POST /v1/imports on the management API with imports:write, source: workos and credentials.api_key. Optional credentials.base_url defaults to https://api.workos.com and must pass public HTTPS checks. Credentials are held only for the source read, never stored in the import.
The reader carries organizations, supported metadata and domains, SAML connections, directories, users, groups and memberships. The source Connection response supplies no IdP metadata or certificates: SAML connections start draft with idp_metadata_required. Source domain status does not grant verified ownership here.
Run it from the CLI
Section titled “Run it from the CLI”The CLI wraps the same import API. Set WORKOS_API_KEY in your shell environment (it is never a flag), then:
- Plan:
ohauthcat migrate plan --from workos. The plan prints each legacy organization, its mapped organization, the migration lever and any blockers, and its import ID. - Run:
ohauthcat migrate run imp_123, then follow progress withohauthcat migrate status imp_123. - Complete the steps below for each organization, then switch it through the API. Undo one organization with
ohauthcat migrate rollback imp_123 org_123.
Complete the metadata step
Section titled “Complete the metadata step”- Run the import and obtain the new organization and connection IDs.
- Create a portal link for the organization with the
migrationintent. - The IT admin supplies exactly one of
saml_metadata_urlorsaml_metadata_xmlin the hosted setup portal. - Verify domains, test sign-in and activate the connection before switching.
The metadata endpoint accepts only an imported draft SAML connection in the session’s organization that has no IdP metadata yet. A connection-pinned link remains pinned. Existing metadata must be changed through ordinary connection editing. Certificates come from supplied metadata, never a live SAMLResponse.
Review what was omitted
Section titled “Review what was omitted”plan.source_skipped lists omitted objects and reasons. Enterprise GenericOIDC, OktaOIDC, EntraIdOIDC and GoogleOIDC connections are included as unconfigured OIDC drafts; social OAuth types are not enterprise SSO. Invalid and deactivated objects can also be skipped. These omissions differ from idp_metadata_required: that SAML connection is included as a draft.
Without explicit custom-domain inputs, the reader uses Lever B. To request Lever A, supply both credentials. and credentials.. The latter is a string containing a JSON-encoded array with exactly connection_id, acs_url and sp_entity_id per imported active SAML connection, copied from actual WorkOS Service Provider Details. Unknown, inactive, non-SAML and duplicate references are refused. Each credential value is limited to 4096 bytes; larger configurations can use a normalized bundle. Core never derives an opaque vendor path. Each ACS must use the exact canonical lowercase domain. The host must already meet the registered broker-host requirements; this does not provision DNS or TLS. See the compatibility bridge for the separate application API flow. Follow cutover and rollback for implemented import controls.
Complete an OIDC draft
Section titled “Complete an OIDC draft”The normalized bundle marks an empty OIDC draft with pending_oidc: true; it does not invent discovery, client credentials or secrets. Use the migration portal OIDC configuration operation to supply the issuer, client ID and IdP-issued secret. Partial configuration remains a draft. Complete configuration moves to pending_test; a fresh successful test and activation are still required. An empty draft exports its marker; a partially configured draft cannot be represented by that marker and export refuses that organization. Re-enter secrets at the destination.
Verify before switching
Section titled “Verify before switching”- Compare included objects and
source_skippedwith the source inventory; do not treat a successful source read as a completed migration. - Confirm preserved legacy IDs and profile mappings in the intended environment. Imported-profile limits apply to new imported rows; existing profiles survive a downgrade.
- Keep imported connections inactive until metadata or OIDC configuration, domain verification and a fresh test are complete.
- For Lever A, verify the actual host and escaped ACS path before moving traffic. For Lever B or C, have the IT admin update the IdP and test the resulting settings.
- Switch the organization only after its required connections are ready, and retain the old route until the rollback checks pass.
The SSO compatibility bridge is a separate application integration. Directory Sync compatibility serves the WorkOS SDK’s Directory Sync reads at their unprefixed paths and sends WorkOS-format webhooks.