Workspace Apps identify your host application when it exchanges identity for a Komo session. Browser and React Native embeds use that session to load protected experiences, keep contact identity consistent, and avoid legacy per-iframe auth flows.

Use Workspace Apps for all new Embed SDK integrations.

When you need one

Create or use a Workspace App for every new embed integration, including:

• Browser configured session authentication with komoEmbed.init.
• React Native provider authentication with KomoClientProvider.
• Anonymous visitor sessions for embedded experiences.
• Host-user identity exchange from JWT or verified attributes.

Visitors without host identity should still receive an anonymous Komo session. Return { type: 'anonymous' } instead of falling back to deprecated no-session flows.

App ID format

Copy the SDK App ID from Komo Portal. It includes the region prefix:

{region}_{appId}

Example:

au1_00000000-0000-0000-0000-000000000000

Use the full prefixed value in SDK setup. Do not pass region separately in new integrations.

Setup checklist

1. Open the relevant workspace in Komo Portal.
2. Create or select the Workspace App for your host website or mobile app.
3. Copy the SDK App ID, including region prefix.
4. Add every browser host origin that will call session exchange to Allowed Origins, for example https://example.com.
5. Enable the identity types your integration returns: JWT, Email, Anonymous.
6. If you return { type: 'jwt', token }, configure JWT signing settings and claim mapping before testing the SDK.
7. Configure your host app to return an identity result from getIdentityToken.
8. Use that App ID in browser komoEmbed.init or React Native KomoClientProvider.

Identity results

getIdentityToken returns the identity payload Komo exchanges for a session:

• { type: 'jwt', token } exchanges an authenticated host-user JWT for an authenticated Komo session.
• { type: 'email', attributes: { email, ... } } exchanges verified host identity attributes for an authenticated Komo session, attributes.email is required. By default, attributes map to matching contact properties by key. Configure custom mappings in the Workspace App when host attribute keys do not match Komo contact property keys.
• { type: 'anonymous' } creates an anonymous Komo session for visitors without host identity.
• { type: 'none' } creates no Komo session and should only be used when the page or app can handle missing session-backed features.

Prefer { type: 'anonymous' } for normal visitor traffic without host identity. { type: 'none' } creates no Komo session; session-backed SDK features will not work.

See Session Authentication for getIdentityToken call timing, session refresh, explicit re-identification, and logout behavior.

Browser setup

Call komoEmbed.init before embed.js loads. Late init calls are ignored.

<script>
(function(n,r,t,c,u,e,f){
  n[u]=n[u]||function(q){return new Proxy(q,{
    get(y,s){return s==="q"?y[s]||[]:
    function(...B){(n[u].q=n[u].q||[]).push([s,...B])}}})
  }({});
  e=r.createElement(t);f=r.getElementsByTagName(t)[0];
  e.async=1;e.src=c;f.parentNode.insertBefore(e,f);
})(window,document,"script","https://KOMO_HUB_URL/assets/embed/embed.js","komoEmbed");

komoEmbed.init('au1_00000000-0000-0000-0000-000000000000', {
  getIdentityToken: async () => {
    const token = await getHostJwt();
    return token ? { type: 'jwt', token } : { type: 'anonymous' };
  }
});
</script>

Continue with the browser embed guide for card covers, triggers, callbacks, session helpers, and deprecated legacy iframe auth.

React Native setup

Wrap embedded content in KomoClientProvider. The provider is required for supported new React Native integrations.

import { KomoCard, KomoClientProvider } from '@komo-tech/react-native';

<KomoClientProvider
  appId="au1_00000000-0000-0000-0000-000000000000"
  getIdentityToken={async () => {
    const token = await getHostJwt();
    return token ? { type: 'jwt', token } : { type: 'anonymous' };
  }}
>
  <KomoCard embedMetaUrl={KomoCardNativeEmbedUrl} />
</KomoClientProvider>;

Continue with the React Native embed guide for provider callbacks, KomoAuthError, useKomoSession, and component APIs.

Common mistakes

• Calling browser init after embed.js loads. Configure it in the loader snippet instead.
• Using an unprefixed App ID. Use {region}_{appId} from Komo Portal.
• Returning { type: 'none' } when visitors still need embeds to work. Return { type: 'anonymous' } instead.
• Passing legacy embedAuthUrl or authPassthroughParams under KomoClientProvider. Provider mode ignores them.
• Mixing configured session auth with deprecated legacy iframe auth on the same integration path.