From Polis (BoxyHQ)
How to import connections and directories from a Polis (BoxyHQ) deployment.
Create a plan with POST /v1/imports on the management API using an imports:write key. Set source: polis and supply credentials.base_url, credentials.api_key and credentials.product. credentials. 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, rather than a successful partial read.
Run it from the CLI
Section titled “Run it from the CLI”The CLI wraps the same import API. Set POLIS_API_KEY in your shell environment (it is never a flag), then:
- Plan:
ohauthcat migrate plan --from polis --source-origin https:. The plan prints each legacy organization, its mapped organization, the migration lever and any blockers, and its import ID./ / sso. example. com --product example-app - 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.
Inspect the plan
Section titled “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.
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. Planning does not provision DNS, TLS or a customer hostname. Resolve those dependencies before changing the host, then follow run, switch and rollback.
Keep the SCIM URL
Section titled “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 (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
Section titled “Verify before switching”- Check the selected product and environment, preserved legacy IDs, included objects and every
source_skippedentry. - 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.
Polis import does not provide a Polis application-API compatibility bridge. Keep application callback changes and IdP changes distinct in the cutover plan.