Implement private Page sign-in

Use this guide to implement the sign-in connection for a private Page. Configure the customer-facing experience in the Pages editor first.

Connect your authenticationCopy Anchor Link

Your existing backend remains responsible for authenticating the user and authorizing their current account. This works with your own sessions or a provider such as Auth0. Configure an RSA public key of at least 2048 bits, issuer, backend sign-in URL, audience (customer or workforce), and any required roles in Access. Keep the private signing key on your backend.

Hosted Page: clicking sign-in opens your configured backend URL with a challenge. Authenticate the user, validate the challenge, and return the proof to the opening Page using postMessage with its exact origin. The Page exchanges the proof for its own HttpOnly session cookie. Do not put proofs in redirect URLs.

Embedded Page: Install supplies the iframe and Pages module connection code. Implement the /pages/proof endpoint referenced by that code. It receives the challenge, authenticates the current backend session and returns { proof }. Enforce the requesting website origin and do not cache this response. The SDK keeps the resulting Page credential in memory and renews it using fresh proofs.

The challenge contains nonce, pageSurfaceId, pageOrigin, and, for embeds, parentOrigin. Validate all of them against your configured integration. Sign a short-lived RS256 JWT with these claims:

Never take the subject, account, roles or audience from an untrusted proof request. For hosted login, send this message to window.opener with pageOrigin as the target origin, then close the popup:

window.opener?.postMessage(
  { source: 'chatbyte-pages-host', type: 'pages.auth.proof', nonce, proof },
  pageOrigin,
);
window.close();

For an embed, call connection.logout() when the user logs out, connection.refresh() after an authorized login or account switch, and connection.destroy() when removing the integration. Hosted sessions expire independently. After logout(), automatic iframe sign-in stays stopped until your application explicitly calls refresh() for an authorized viewer. Logging out of your website does not automatically send a logout event to another open Page tab. Private Page sessions expire after 15 minutes.

Before releasing a private integration, test account switching, expired sessions, logout, rejected roles and reopening an existing conversation with your real identity provider. Never forward the provider's access token as a Page proof.