POST / uses imports:write on the management API. Send import and legacy_profile_id; the response contains the mapped OhAuthCat profile.
Your server must first authenticate the existing session with the old provider, for example through UserInfo. Derive the legacy profile ID from that trusted result. A client-supplied ID alone is not authentication. Never send the old access token to OhAuthCat: this endpoint neither validates a provider token nor calls UserInfo.
The import must be running or completed. The profile must map through imported legacy IDs to an organization that has not rolled back. Bundles can include per-connection profiles so mapping works before the first sign-in here; credentials readers do not fabricate profiles missing from source APIs. The email domain must still be verified for the organization.
Each legacy profile is migrated once per import. Repeated or ambiguous mappings return import_state_conflict; absent mappings are not found, and failed domain proof returns email_outside_verified_domain. Reconcile an ambiguous timeout rather than replaying it to mint multiple sessions.
The endpoint returns a profile, not an access token or your application’s session cookie. Check its organization against the authenticated tenant, then update your own session according to your policy. Routing rollback does not undo those application sessions.
SDK resolver contract
Section titled “SDK resolver contract”The SDK helpers accept the old access token only inside your application. Configure a resolver that authenticates it with the old provider and returns the trusted legacy profile ID. The helper sends only the import ID and resolved profile ID to OhAuthCat. Keep provider credentials and tokens out of logs, URLs and browser-visible configuration.
Node uses client.. The resolver receives (token, signal) and returns a promise containing the trusted ID. Call helper.; signal is optional. Honor the supplied abort signal in provider requests.
Python uses client.. A sync resolver returns the trusted ID; an async resolver awaits it. Both receive the token and a LegacySessionContext with a deadline, cancellation check and remaining_seconds(). Use that remaining budget for provider requests. Call helper. on the sync client, or await it on the async client.
Go configures ResolveLegacyProfile as func( in MigrationConfig. Call helper. and honor the resolver’s context. LegacyProvider identifies the expected imported legacy mapping; the supported values are workos, polis and generic.
Session migration also reads the import, so a helper key needs imports:read as well as imports:write. The helpers check the import state and returned mapping, but your resolver remains responsible for authenticating the legacy session. Keep the final tenant check and application-session update on your server. A routing helper result alone does not authenticate a user.
Pinned SDK examples
Section titled “Pinned SDK examples”These examples use the reviewed development SDK sources, not an assumed published package release. The resolver is a synthetic test fixture, not token authentication. Replace it with trusted provider verification before using the helper in an application; never derive identity by decoding an unverified token or accepting a browser-supplied ID. Configure the secret key only on your server.
import { OhAuthCat } from "@ohauthcat/node";
const apiKey = process.env.OHAUTHCAT_API_KEY;if (!apiKey) throw new Error("Missing server API key");const client = new OhAuthCat({ apiKey, timeoutMs: 5000, maxRetries: 0, apiBaseUrl: process.env.OHAUTHCAT_API_ORIGIN,});const helper = client.migration({ importId: "imp_01ARZ3NDEKTSV4RRFFQ69G5FAV", legacyProvider: "workos", // Test fixture only: replace with authenticated provider verification. resolveLegacyProfile: async (token, signal) => { signal.throwIfAborted(); if (token !== "documentation-legacy-token") { throw new Error("Legacy session refused"); } return "legacy-documentation-profile"; },});
export function routingForOrganization(organization) { return helper.routing.forOrganization(organization);}
export function migrateExistingSession(legacyToken) { return helper.migrateSession({ legacyAccessToken: legacyToken });}
export function closeClient() { client.close();}import osfrom ohauthcat import OhAuthCat
api_key = os.environ.get("OHAUTHCAT_API_KEY")if not api_key: raise ValueError("Missing server API key")client = OhAuthCat( api_key=api_key, timeout_ms=5000, max_retries=0, api_base_url=os.environ.get("OHAUTHCAT_API_ORIGIN"),)
def resolve_legacy_profile(token, context): # Test fixture only: replace with authenticated provider verification. context.remaining_seconds() if token != "documentation-legacy-token": raise ValueError("Legacy session refused") return "legacy-documentation-profile"
helper = client.migration( import_id="imp_01ARZ3NDEKTSV4RRFFQ69G5FAV", legacy_provider="workos", resolve_legacy_profile=resolve_legacy_profile,)
def routing_for_organization(organization): return helper.routing.for_organization(organization)
def migrate_existing_session(legacy_token): return helper.migrate_session(legacy_access_token=legacy_token)
def close_client(): client.close()Close the client during application shutdown, after in-flight work has finished. These functions return SDK results to your server; they do not set an application cookie. Validate the returned profile’s organization against the authenticated tenant before creating your session.