# Session cutover

`POST /v1/sessions/migrate` uses `imports:write` on the [management API](/reference/api/management/). 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`](/errors/import_state_conflict/); absent mappings are not found, and failed domain proof returns [`email_outside_verified_domain`](/errors/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](/migrate/cutover-and-rollback/) does not undo those application sessions.

## 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.migration({ importId, resolveLegacyProfile })`. The resolver receives `(token, signal)` and returns a promise containing the trusted ID. Call `helper.migrateSession({ legacyAccessToken, idempotencyKey })`; `signal` is optional. Honor the supplied abort signal in provider requests.

Python uses `client.migration(import_id=import_id, resolve_legacy_profile=resolver)`. 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.migrate_session(legacy_access_token=token, idempotency_key=key)` on the sync client, or await it on the async client.

Go configures `ResolveLegacyProfile` as `func(context.Context, string) (string, error)` in `MigrationConfig`. Call `helper.MigrateSession(ctx, legacyToken, idempotencyKey)` 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

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.

```javascript
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();
}
```

```python
import os
from 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.
