POST /v1/imports
- Scope
imports:write- Auth
- Secret key (
sk_…) - Since
- 1.0
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Honoured for 24 h; a replay returns the original response.Idempotency-Keystringmin length 1 · max length 255
Request body
Section titled “Request body”
The source to read.sourcestring Requiredauth0andcsv_samlare read only by their adapter (Auth0credentials, or acsv_samlbundle_upload_id); an inlinebundlewith either source is refused withparameter_invalid. One environment has at most one planned or runningauth0orcsv_samlimport; another answersimport_state_conflict(409) until it completes, fails or is cancelled;GET /finds it, and a planned one is cancelled automatically after 24 hours. Creatingv1/ imports? state=planned auth0andcsv_samlimports is also limited to 20 per hour per environment (rate_limited, 429, withRetry-After). Acsv_samlarchive names at most 100 distinct metadata URLs, each fetched once, and its whole read is bounded to 50 seconds. Anauth0read, Management API retries included, is bounded to 50 seconds too.one of
polis,workos,auth0,csv_saml,bundle
Read the source’s management API once, with these credentials, instead of sending a bundle. Polis/WorkOS authentication credentials and API keys are used only for this request, never stored. Auth0 uses tenant_domain, client_id and client_secret for a canonical Auth0 tenant host, with read:connections only; like Polis/WorkOS credentials they are used only for this request and never stored. Credentials are never logged or returned. Auth0 offset pagination refuses sources exceeding its documented 1000-connection capacity. Custom Auth0 tenant domains are currently refused. Nonsecret migration settings are copied into the normalized bundle and connection configuration and may appear in exports.credentialsobjectpolis:base_url(https),api_key,product, optionalsp_entity_id(the deployment’s SAML audience) andexternal_url(the deployment’sEXTERNAL_URLwhen IdPs reach it on another origin thanbase_url; its shared ACS<external_url>becomes/ api/ oauth/ saml legacy_shared_acs_url).workos:api_key, optionalbase_url(defaulthttps://api.workos.com); optional pairedcustom_auth_domainandcustom_auth_connectionsconfigure custom-domain migration. The domain must be a canonical lowercase ASCII hostname, without a port or trailing dot. The connections value is a JSON array of objects with exactlyconnection_id,acs_urlandsp_entity_id, copied from the actual WorkOS Service Provider Details; every imported active SAML connection needs one record and unknown, inactive, non-SAML or duplicate references are refused. Each ACS URL must use that exact domain. No vendor identifier or path is inferred. Each credential value is limited to 4096 bytes; larger setups can send a normalized bundle. WorkOS exports no IdP metadata, so its SAML connections import as drafts withidp_metadata_requireduntil the IT admin supplies it through amigrationportal link. Every request goes through the safe fetcher; a refused key or an unreachable or non-public source answersimport_source_unreachable.
A valid, unexpired, unconsumed upload of this environment. csv_saml selects a closed ZIP containing connections.csv and flat named metadata XML files; other sources select import_bundle. The uploaded document must match its declared size and pass the same validation as an inline bundle. Consumption and creation of the planned import are atomic; workers use the frozen import bytes.bundle_upload_idstring
Optional unconsumed auth0_users JSON lines export of this environment, at most 64 MiB. Allowed only with Auth0 credentials. The exporter must establish the unchanged upstream IdP subject; an unverified provider-specific identity is refused, and the original export is never returned.users_upload_idstring
Optional unconsumed auth0_mapping UTF-8 CSV with connection_id,organization_external_id,organization_name columns. Allowed only with Auth0 credentials, at most 5 MiB; explicit mapping takes precedence over source metadata.mapping_upload_idstring
The normalized migration format (version 1). It never carries secrets (OIDC client secrets, SCIM tokens, private keys). At most 16 MiB, 500 organizations and 100000 directory users.bundleImportBundle
Responses
Section titled “Responses”- 201 OK Import
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
Errors share one shape; see the error code catalogue.
curl -X POST \ "https://api.ohauthcat.com/v1/imports" \ -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "polis"}'const response = await fetch("https://api.ohauthcat.com/v1/imports", { method: "POST", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "source": "polis" }),});const data = await response.json();import osimport requests
response = requests.post( "https://api.ohauthcat.com/v1/imports", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "source": "polis", },)data = response.json(){ "id": "imp_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "object": "import", "source": "polis", "state": "planning", "plan": { "organizations": [ { "organization_id": "org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "lever": "A", "routing": "legacy", "blockers": [ "example_blocker" ], "legacy_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "name": "Acme Corp", "state": "pending", "error_code": "saml_signature_invalid", "refused": "example_refused", "items": [ {} ], "imported_at": "2026-01-15T09:30:00Z", "switched_at": "2026-01-15T09:30:00Z", "rolled_back_at": "2026-01-15T09:30:00Z" } ], "summary": { "create": 1, "draft": 1, "skip": 1, "users": 1, "groups": 1 }, "source_skipped": [ { "kind": "default", "legacy_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "reason": "Primary SSO connection for Acme Corp." } ], "custom_hostnames": [ { "hostname": "acme.com", "type": "default" } ] }, "bundle_source": "polis", "created_at": "2026-01-15T09:30:00Z", "updated_at": "2026-01-15T09:30:00Z", "completed_at": "2026-01-15T09:30:00Z"}