Skip to main content

Getting Started

Iframe URL​

${PRIVATEKIT_ORIGIN}/private-kit
  • PRIVATEKIT_ORIGIN — the deployed origin of the auth-central application (production / staging).
  • No token is encoded in the URL. The iframe is stateless on mount — it does not know who the user is until the host sends an action with an authToken.

Minimal embed​

<iframe
  src="https://auth.example.com/private-kit"
  title="private-kit"
  style="border:0; width:100%; height:100%"
></iframe>

As soon as the iframe mounts, it sends a PRIVATE_KIT_INIT message to window.parent containing the newly generated connectionId. The host must subscribe to message events to receive it. See Protocol for the full message rules and Integration Example for a complete React snippet.

Required setup checklist​

Before the iframe can run a private action for your user, you need:

  1. A valid private authToken for the current user — the same JWT that you would put in an Authorization: Bearer … header against the auth-central /private/api/v1 endpoints. Typically you read this from the same cookie that the auth-central web flow sets (auth_token).
  2. A way to refresh the token when PrivateKit returns AUTH_TOKEN_401 (use the standard /users/refresh flow used elsewhere in the app — see useAccountRefreshToken).
  3. A message event listener on window that:
    • filters inbound messages by event.origin === PRIVATEKIT_ORIGIN;
    • captures connectionId from PRIVATE_KIT_INIT;
    • routes subsequent messages by payload.connectionId.

When to use PrivateKit vs. opening the standalone page​

The auth-central app exposes standalone web pages for each private action (e.g. /account/change-username). They render their own form, do their own validation, and close the window on success. Use them when you want auth-central to own the UX entirely.

Use PrivateKit instead when your host application wants to keep the UI inside its own design system, but still delegate the authenticated API call and validation rules to auth-central. The iframe stays invisible (height: 0) and the host renders the input field.