Skip to content
Dashboard
Theme
Theme

Plan an import

POST /v1/imports: Plan an import.

View Markdown

POST /v1/imports

Scope
imports:write
Auth
Secret key (sk_…)
Since
1.0
  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • Idempotency-Key string

    Honoured for 24 h; a replay returns the original response.

    min length 1 · max length 255

  • source string Required

    The source to read. auth0 and csv_saml are read only by their adapter (Auth0 credentials, or a csv_saml bundle_upload_id); an inline bundle with either source is refused with parameter_invalid. One environment has at most one planned or running auth0 or csv_saml import; another answers import_state_conflict (409) until it completes, fails or is cancelled; GET /v1/imports?state=planned finds it, and a planned one is cancelled automatically after 24 hours. Creating auth0 and csv_saml imports is also limited to 20 per hour per environment (rate_limited, 429, with Retry-After). A csv_saml archive names at most 100 distinct metadata URLs, each fetched once, and its whole read is bounded to 50 seconds. An auth0 read, Management API retries included, is bounded to 50 seconds too.

    one of polis, workos, auth0, csv_saml, bundle

  • credentials object

    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. polis: base_url (https), api_key, product, optional sp_entity_id (the deployment’s SAML audience) and external_url (the deployment’s EXTERNAL_URL when IdPs reach it on another origin than base_url; its shared ACS <external_url>/api/oauth/saml becomes legacy_shared_acs_url). workos: api_key, optional base_url (default https://api.workos.com); optional paired custom_auth_domain and custom_auth_connections configure 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 exactly connection_id, acs_url and sp_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 with idp_metadata_required until the IT admin supplies it through a migration portal link. Every request goes through the safe fetcher; a refused key or an unreachable or non-public source answers import_source_unreachable.

  • bundle_upload_id string

    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.

  • users_upload_id string

    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.

  • mapping_upload_id string

    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.

  • bundle ImportBundle

    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.

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"
}'
Response 201
{
"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"
}