Cutover and rollback
How to switch an organization to OhAuthCat, verify it, and roll it back if something goes wrong.
These operations use the management API and environment-scoped keys.
POST /v1/importsrequiresimports:write.GET /v1/imports/{imp}requiresimports:read.POST /requiresv1/ imports/ {imp}/ run imports:write.POST /requiresv1/ imports/ {imp}/ organizations/ {org}/ switch imports:write.POST /requiresv1/ imports/ {imp}/ organizations/ {org}/ rollback imports:write.POST /requiresv1/ imports/ {imp}/ cancel 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
Section titled “Run and verify”Check 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.
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 afterward.
Wire routing into your application
Section titled “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 separately for authenticated users and export for portable configuration.
SDK routing helpers
Section titled “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. and helper.. Pass { refresh: true } to bypass the cached route for that read. In Python, use client. and helper.; the async client exposes the same methods with await.
Both helpers default to a 30-second routing cache. Call helper. 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. returns a helper and an error. Set ImportID, then call helper.. helper. 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.