# Cutover and rollback

These operations use the [management API](/reference/api/management/) and environment-scoped keys.

- `POST /v1/imports` requires `imports:write`.
- `GET /v1/imports/{imp}` requires `imports:read`.
- `POST /v1/imports/{imp}/run` requires `imports:write`.
- `POST /v1/imports/{imp}/organizations/{org}/switch` requires `imports:write`.
- `POST /v1/imports/{imp}/organizations/{org}/rollback` requires `imports:write`.
- `POST /v1/imports/{imp}/cancel` requires `imports:write`.

Creating an import stores its plan without creating planned tenant resources. Read the import to inspect items, blockers, organization states and routing. Running queues the persisted bundle for a background worker and returns HTTP 202. Read status to follow progress; the response does not mean the import has finished. Switching sets routing to `ohauthcat`; rollback sets it to `legacy`. Canceling requires a permitted import state.

For an inline bundle, set `source: bundle` and put the `ohauthcat.import_bundle` version 1 object in `bundle`. The bundle's own source identifies its legacy mappings. Send exactly one input: `bundle`, source `credentials` or `bundle_upload_id`. For uploaded input, first create an upload with `POST /v1/uploads` through the management API, send exactly the declared `size_bytes` to `upload_url` with `upload_method` and every value in `upload_headers`, then create the import with `bundle_upload_id` before `expires_at`. The maximum upload is 16 MiB. Content-Type is not promised to be signed. Validation and planning freeze the uploaded bundle before its single-use upload is consumed; later object changes cannot alter the queued import. Auth0 and CSV adapters are not implemented.

## Run and verify

Check [imported-profile limits](/migrate/imported-profile-limits/) before running a bundle containing profiles. A limit refusal applies to the affected organization; inspect the persisted organization states before retrying.

Review the plan first. Planning reads the target but does not fetch metadata URLs; running fetches through the safe fetcher. Run is transactional per organization, idempotent by environment/source/legacy ID and resumable. After a timeout, read status before taking another action rather than creating a duplicate import. Workers resume persisted organization states under a renewed lease. Cancellation interrupts worker progress; it is not an ordinary organization failure. Invalid state transitions return [`import_state_conflict`](/errors/import_state_conflict/).

Connections start `pending_test` or `draft`, never active. Domains need fresh verification. Resolve blockers, test and activate each imported connection. Switching requires every imported connection for the organization to be active. Watch [sign-in history](/sso/sign-in-history/) afterward.

## Wire routing into your application

The import stores a routing flag; it does not redirect your existing traffic by itself. Your server must read current import routing and choose the old provider or OhAuthCat. Keep the old provider and configuration available during verification and rollback. Automatic shadow comparison is not promised here.

Rollback changes the routing flag in one transaction. It does not undo external DNS or IdP changes, erase data, revoke your application's sessions or restore secrets. With `cleanup: true`, imported active connections become inactive and need activation before switching again. An invalid state returns `import_state_conflict`.

Use [session cutover](/migrate/session-cutover/) separately for authenticated users and [export](/migrate/export/) for portable configuration.

## SDK routing helpers

The SDKs expose an import-bound migration helper. Configure its import ID on your server, then ask its routing helper for the authenticated organization's route. The result is `legacy` or `ohauthcat`; your application chooses the corresponding provider. A lookup failure is an error, not permission to silently choose a provider.

In Node, use `client.migration({ importId })` and `helper.routing.forOrganization(organizationId)`. Pass `{ refresh: true }` to bypass the cached route for that read. In Python, use `client.migration(import_id=import_id)` and `helper.routing.for_organization(organization_id, refresh=True)`; the async client exposes the same methods with `await`.

Both helpers default to a 30-second routing cache. Call `helper.routing.invalidate()` after your application switches or rolls back routing. Other application processes may still hold their own cached route, so refresh important cutover decisions and allow for that cache window.

In Go, `client.Migration(MigrationConfig)` returns a helper and an error. Set `ImportID`, then call `helper.Routing.ForOrganization(ctx, organizationID)`. `helper.Routing.Invalidate()` clears its cache; `CacheTTL` changes the default 30 seconds and `DisableCache` disables it. These methods do not switch an organization or construct an authorization request automatically.
