Moving off Session Restarts

The ability to call omni/start again on a session that already exists, referred to as a restart, is being retired. If your integration does this, you need to migrate to one of the replacement paths below before the enforcement date.

At a glance

What is changing

The 48-hour rule governs session resume only. A session can be resumed via /omni/session/continue within 48 hours of the omni/start call that created it, up to twice. Resuming does not extend the window, and once it closes a new session is required. The 48 hours do not apply when a session is only being read using an admin token; there is no limit on session age in that case.

Enforcement

The enforcement date is 30 September 2026. There is no reset at that date and no grace period: the 48 hours are measured from each session's own omni/start call, so a session created more than 48 hours before enforcement cannot be resumed once enforcement begins.

After the enforcement date, a restart on a session outside its 48-hour window returns HTTP 400:

The /omni/session/continue endpoint returns a distinct response for each rejection case.

Find your scenario

Work through these in order. The first match is your scenario. An integration may fall into more than one, in which case handle each separately.

Scenario 1: Reading session data

Applies when: the integration calls omni/start again purely to mint a token, then uses that token to read data. The restart is a side effect of needing a token, not something the flow requires.

What to do instead: authenticate with an admin token and pass the session's interviewId explicitly. No session is opened.

Prerequisites:

• Provision an admin user: A dashboard user with the Admin role is required on the specific instance being called. The admin token is issued in exchange for that user's email and password. If the account is removed or its password changes, the integration stops working.

• Obtain and refresh the admin token.

The endpoints you'll call

The admin token goes in the X-Incode-Hardware-Id header, not Authorization: Bearer. The session is identified by interviewId as a query parameter, which is what allows an existing session to be read without opening it.

curl -X GET 'https://<api-base>/omni/get/ocr-data?id=<interviewId>' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-incode-hardware-id: <ADMIN_TOKEN>' \
  --header 'api-version: 1.0'

Images. Use POST /omni/get/images/v2, documented at get-images-v2 as "Fetch image links". It returns pre-signed download URLs valid for one hour. The v1 path POST /omni/get/images returns base64 instead, and responses over 10MB fail at the API gateway. New integrations should use v2.

Session age. There is no age restriction on reads made with an admin token. A session from any point in the past can be read, provided its interviewId is known.

Log in to obtain a token:

curl -X POST 'https://<api-base>/executive/log-in' \
  --header 'api-version: 1.0' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "<admin user email>", "password": "<password>" }'

The response contains token (the admin token, a JWT), plus refreshToken and incodeRefreshToken. Reference: executive/log-in.

One admin token works across all sessions. Store it and reuse it rather than calling /executive/log-in for each request. The token expires after 24 hours by default. Store the expiry alongside the token and request a new one before it lapses, rather than waiting for a call to fail. Refresh via POST /executive/refresh, passing the refresh token in the X-Incode-Hardware-Id header. The incodeRefreshToken is single-use and is invalidated on logout.

After migration: remove the old path

Remove any code path that calls omni/start with an existing interviewId or externalId in order to obtain a token for reading.

Storing a session token is not an alternative. The session token TTL is configurable and currently defaults to 90 days; that default is being reduced to 20 minutes.

Scenario 2: Resuming an interrupted session

Applies when: a real user abandons a flow partway and the session is restarted so they can pick up where they left off.

What to do instead: call /omni/session/continue to obtain a fresh token for the same session. Available within 48 hours of the omni/start call that created the session, up to two times.

What the change looks like

1. Call /omni/session/continue to obtain a new session token. The session token is scoped to that single session and is passed in the X-Incode-Hardware-Id header, the same as the token returned by omni/start.
2. Resume the user at the right step. If you want the user to pick up exactly where they left off, you need your own record of how far they progressed.
3. Handle rejection. A continue call fails when either the 48 hours have elapsed or the session has already been continued twice. On rejection, start a new session.

/omni/start continues to accept its current behavior during the migration period, so the switch does not have to be made in a single step. For the request and response contract, see the API reference.

Scenario 3: Step-up and additional checks

Applies when: an existing or completed session is reopened to run an extra verification step or collect another document: a signature, a proof of address, a tier upgrade, or a renewed terms acceptance.

What to do instead: start a new session, begin it with authentication against the existing identity, and reference the original via identityId so both remain associated under one identity.

A. Step-ups involving a signature (including NOM-151, AES, or QES)

Development is underway to let a new session retrieve the signature and OCR data from the identity. Endpoint details will follow.

B. Step-ups that do not involve a signature

Examples include collecting a proof of address months after onboarding or upgrading an account tier.

These are not covered by the 30 September date. Existing behavior continues to work, and guidance will be provided separately.

Scenario 4: Repeating a completed onboarding

Applies when: a user completed onboarding successfully, and days, weeks, or months later the finished session is restarted rather than a new one created. The session was not interrupted partway; it completed.

What to do instead: create a new session for each attempt.