SSO configuration

Use SSO when your website or product already has authenticated users and you want a Zeeker embed to recognize those sessions. The full integration reference is under Embed → SSO.

Community settings

Select a community in the Admin Center and open SSO. The current JWT-bridge configuration is community-wide and contains:

• Status — SSO moves from Draft to Verified to Active. A draft is never shown to visitors.
• Provider — jwt-bridge is implemented today; OIDC is reserved for later.
• Button label and icon — branding used when Zeeker ID offers the parent sign-in method.
• HMAC secret — shared HS256 secret used only by your backend and Zeeker.
• Allowed email domains — optional allow-list; an empty list accepts any domain.
• Redirect URL — parent-site handoff used when Zeeker ID is reached outside an embed. It is required for JWT-bridge SSO on a standalone community home, custom domain, or post deep link.

Generating an HMAC secret returns it once. Store it in your server-side secret manager. Later reads expose only whether a secret is configured.

Save the configuration as a draft, implement the handoff endpoint, then select Test & enable SSO. The test opens the real endpoint in a browser, requires it to return a fresh correctly signed JWT, and only activates the exact tested URL, secret, and domain policy. Changing any of those identity settings disables SSO until the new version passes again. A homepage, static HTML page, unsupported provider, or endpoint that ignores the supplied callback cannot become active.

Per-embed behavior

The provider is never reconfigured per embed. The Embed configurator reads this community connection's enabled status and exposes two per-embed choices:

• Sign-in method — Community SSO, Zeeker login, or SSO or Zeeker login.
• When to sign in — On gated action, Automatically on load, or Managed by host app.

Automatically on load emits sso-required during boot. Managed by host app emits auth-required for a gated read/action and waits for the host to call window.zeeker.identify(jwt) instead of opening Zeeker ID. Both require enabled community SSO and an SSO-capable sign-in method.

With SSO or Zeeker login, selecting sign-in inside that community opens Zeeker ID with the configured SSO method first and keeps standard phone, email, and social methods under Other Options. With Community SSO, only the host bridge is used. Requests started inside nested Zeeker frames are source- and correlation-checked by the widget before they surface through the public event API.

For standalone community pages, configure an HTTPS redirect URL with a non-root handler path. It must authenticate the visitor on your site, mint a fresh short-lived JWT, and return it to the Zeeker callback URL supplied in the request. Zeeker keeps unverified or stale configurations in Draft state and leaves regular login available.

Account behavior

An identity that is already linked by community plus stable parent sub signs in directly. A first-time identity always completes a blocking Zeeker ID screen before account creation. The required username and verified parent email appear with optional display name, city, and interests in the same form.

If the JWT email already belongs to an unlinked Zeeker account, Zeeker requires that account to be verified before adding the SSO link.

JWT contract

Your backend signs an HS256 JWT with the configured secret. sub, email, iat, and exp are required for connection verification. name, avatar_url, and nbf are optional. The token must be freshly issued and expire within five minutes.

const token = jwt.sign(
  { sub: user.id, email: user.email, name: user.name },
  process.env.ZEEKER_SSO_SECRET,
  { algorithm: 'HS256', expiresIn: '5m' },
);

The browser obtains this token from your authenticated backend and passes it to window.zeeker.identify(token). See Embed SSO for the complete host-page example and response statuses.

Rotating or revoking access

Generate and save a new HMAC secret, update your parent backend to use it, and stop minting with the previous value. Replacing or clearing the configured secret prevents new exchanges signed with the old value. Existing short-lived Zeeker sessions expire independently.