# From WorkOS

Use `POST /v1/imports` on the [management API](/reference/api/management/) 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

The [CLI](/get-started/cli-commands/#ohauthcat-migrate) wraps the same import API. Set `WORKOS_API_KEY` in your shell environment (it is never a flag), then:

1. 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.
2. Run: `ohauthcat migrate run imp_123`, then follow progress with `ohauthcat migrate status imp_123`.
3. Complete the steps below for each organization, then [switch it](/migrate/cutover-and-rollback/) through the API. Undo one organization with `ohauthcat migrate rollback imp_123 org_123`.

## Complete the metadata step

1. Run the import and obtain the new organization and connection IDs.
2. Create a [portal link](/hosted-portal/portal-links/) for the organization with the `migration` intent.
3. The IT admin supplies exactly one of `saml_metadata_url` or `saml_metadata_xml` in the hosted setup portal.
4. 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

`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.custom_auth_domain` and `credentials.custom_auth_connections`. 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](/sso/custom-domains/); this does not provision DNS or TLS. See the [compatibility bridge](/migrate/compat-workos/) for the separate application API flow. Follow [cutover and rollback](/migrate/cutover-and-rollback/) for implemented import controls.

## 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

- Compare included objects and `source_skipped` with 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](/migrate/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](/migrate/cutover-and-rollback/) pass.

The [SSO compatibility bridge](/migrate/compat-workos/) is a separate application integration. [Directory Sync compatibility](/directory-sync/workos-compat/) serves the WorkOS SDK's Directory Sync reads at their unprefixed paths and sends WorkOS-format webhooks.
