# From Polis (BoxyHQ)

Create a plan with `POST /v1/imports` on the [management API](/reference/api/management/) using an `imports:write` key. Set `source: polis` and supply `credentials.base_url`, `credentials.api_key` and `credentials.product`. `credentials.external_url` is optional when the externally visible legacy host differs from the source API host. The source must be public HTTPS; private and loopback addresses are refused.

Credentials are used for this request and are not stored, logged or placed in the bundle. Supply them from your server's secret store. Source authentication, network and repeated rate-limit failures return [`import_source_unreachable`](/errors/import_source_unreachable/), rather than a successful partial read.

## Run it from the CLI

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

1. Plan: `ohauthcat migrate plan --from polis --source-origin https://sso.example.com --product example-app`. 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`.

## Inspect the plan

The reader imports product-scoped connections and directories with users, groups and memberships, preserving supported legacy IDs. When Polis returns its configured IdP entity ID, SSO URL and signing certificate in `idpMetadata`, SAML can proceed without the WorkOS metadata step. Inspect the actual blockers for missing or incomplete configuration.

Default deployments share a legacy ACS such as `/api/oauth/saml`. Imported connections can share that alias. The broker uses the SAML Issuer as a routing hint: exactly one matching connection in the state's environment must exist, and it must be the connection bound to that state. Signature, audience, destination and domain checks still apply. An issuer collision produces `acs_alias_issuer_taken`.

Review `plan.source_skipped`: entries have `kind`, `legacy_id` and `reason`. Unsupported, invalid, duplicate and deactivated objects can be left out. This report describes omitted objects, not passwords or secrets. The credentials reader does not read a portable profile list; supply supported profile mappings in an explicit bundle for [session cutover](/migrate/session-cutover/).

When such a connection's only legacy ACS is the shared alias, and that alias sits on a verified `broker` or `broker_scim` custom hostname of the same environment, sign-in requests name the shared legacy ACS URL in the AuthnRequest. The URL is the one the IdP already has configured, so no IdP administrator needs to change anything. This happens only when the connection's IdP entity ID matches exactly one connection registered on that host and path; otherwise the request names the native ACS, as before. A `preferred_acs_url` always wins, and the response is still routed by Issuer and fully verified.

An eligible customer-owned legacy host can plan [Lever A](/migrate/levers/). Planning does not provision DNS, TLS or a customer hostname. Resolve those dependencies before changing the host, then follow [run, switch and rollback](/migrate/cutover-and-rollback/).

## Keep the SCIM URL

A self-hosted Polis usually serves SSO and SCIM on one hostname. `plan.custom_hostnames` lists every customer-owned hostname the old deployment served, each with the custom domain type to add before switching. A hostname listed as `broker_scim` served both: add it as a [`broker_scim` custom domain](/sso/custom-domains/#sign-in-and-scim-on-one-hostname) (Business and above), and the directories' SCIM base URL stays the same. SCIM administrators still paste a newly issued directory token in their identity provider, because tokens are never imported.

## Verify before switching

- Check the selected product and environment, preserved legacy IDs, included objects and every `source_skipped` entry.
- Validate the supplied IdP metadata and certificates. Imported connections still require a fresh test and activation. A Polis tenant is only a label, so the import creates no domains: add each organization's domains after the import and verify them.
- For shared ACS paths, resolve issuer collisions before cutover. Never use the issuer hint as authentication or merge tenants to bypass a collision.
- Hand over newly issued directory tokens and verify domain ownership before users become eligible.
- Supply explicit profile mappings where session cutover needs them, within the [imported-profile limits](/migrate/imported-profile-limits/).

Polis import does not provide a Polis application-API compatibility bridge. Keep application callback changes and IdP changes distinct in the cutover plan.
