Book a demo

Session authentication exchanges host identity for a Komo session. Browser and React Native embeds use that session to load experiences, keep contact identity consistent, and refresh access without asking your app for identity on every embed open.

Start with Workspace Apps to create and copy your SDK App ID, then use this page to understand session lifecycle behavior.

When getIdentityToken runs

getIdentityToken runs when the SDK needs to create a new Komo session from host identity. It does not run on every embed open or every session refresh.

The SDK calls getIdentityToken when:

  • An embed first needs a Komo session and no usable session token exists.
  • Host code explicitly asks to identify again with komoEmbed.identifyUser() or React Native useKomoSession().identify().
  • The current session token is expired and the SDK needs a new identity exchange.
  • A session refresh fails because the existing Komo token is invalid or expired, and the SDK falls back to identity exchange.

The SDK does not call getIdentityToken when a current session token is still usable. Near expiry, it refreshes the Komo session token directly. Concurrent identity calls are deduplicated so only one getIdentityToken call is in flight for that exchange.

A previous token stored in the browser tab does not skip this call. Same-tab refresh still runs identity exchange. See Same-tab page refresh.

Session refresh

After a successful identity exchange, the SDK stores the Komo session token and expiry. Before expiry, it refreshes the Komo session token directly without calling getIdentityToken again.

If refresh fails because the Komo session token is invalid or expired, the SDK falls back to a new identity exchange and calls getIdentityToken.

Same-tab page refresh

On a same-tab browser refresh, the SDK still runs identity exchange and still calls getIdentityToken. Host identity wins every reload.

If the tab stored a prior session token, the SDK sends that string only as a previous-session hint. An Anonymous prior can continue as the same contact. The stored JWT is not a restored live session: it is not hydrated onto the current session, and it is not refreshed as a live token.

If the stored token is missing, Identified/Verified, or invalid, attach does not run. Identify still succeeds on the usual path: a new anonymous contact, or email/JWT lookup.

React Native does not persist a previous session token.

Explicit re-identification

Call explicit identify APIs when your host app identity changes or when your UI needs to retry authentication after a recoverable failure:

await komoEmbed.identifyUser();
const komoSession = useKomoSession();
await komoSession.identify();

These APIs force a new identity exchange using the latest getIdentityToken result.

Logout

On the browser SDK, logoutUser() mints a new anonymous visitor. It does not leave a sessionless host.

The call clears the current session and the stored previous-token hint, exchanges anonymous identity with no previous session token, and stores the new JWT. In-page embeds remount with that anonymous session. Overlay experiences close; opening again uses the new anonymous session.

Host identity is not re-applied until you call identifyUser(). Successful identifyUser() still adopts into a live in-page embed in place. Logout remounts because the new session is anonymous.

Configured forgetUser() aliases logoutUser().

await komoEmbed.logoutUser();

React Native logout() still clears the current Komo session and prevents automatic re-authentication until host code explicitly identifies again.

const komoSession = useKomoSession();
komoSession.logout();