Buddy Docs Open Studio

Authenticating Your Users

The widget receives the user's identity token over a secure, origin-locked postMessage handshake. The token is held only in memory and forwarded once to Buddy for verification — it is never placed in the URL, cookies, or local storage.

Embed the widget

<script
  src="https://buddy.ui.pe/app/embed.js"
  data-token="YOUR_SHARE_LINK_TOKEN"
  data-auth-token="USER_IDENTITY_TOKEN"
  defer
></script>

If your user token refreshes (most do), set it at runtime instead of the static data-auth-token attribute: 

// Call this whenever you have a fresh token for the signed-in user.
window.BuddyWidget.setAuthToken(await getUserToken());

How the handshake works

  1. The chat iframe loads and posts { type: "buddy:ready" } to your page.
  2. Your embed script replies { type: "buddy:auth", token } — sent only to the Buddy origin.
  3. The iframe forwards the token to the API on its first request via the X-User-Auth-Token header.
  4. Buddy verifies the token and, on success, starts an authenticated session for that conversation.

Anonymous fallback

If no token arrives within a short window, or verification fails, the chat continues anonymously — the agent simply answers without account context. This means a momentary auth hiccup never blocks the conversation.

No method configured

If an agent has no authentication method set, any token is ignored and the session stays anonymous (error code AUTH_NOT_CONFIGURED). Configure a method under Connections → User authentication.