Zum Hauptinhalt springen

Account Linkage

If your app already federates its users to Appilot via the widget token API (see Installation under "Connecting your users") AND some of your users also use the Appilot Chrome extension, you can offer account linkage. Linking ties a user's Appilot account to their identity in your app, so both surfaces (the extension and your embedded widget) recognise the same person, share conversations, and apply the same role.

Linking is opt-in and confirmed once per user, per app. It never lets your app spend the user's personal credits; it only governs which identity the two surfaces resolve to.

The trust model​

A meta tag initiates linkage; a server-signed token confirms it. The extension never trusts a raw value from your page's DOM for anything that affects billing or identity, only a token your backend signs.

1. Declare the integration (two meta tags)​

Add these to your page <head> for signed-in users:

<meta name="appilot:widget-key" content="wk_live_your_publishable_key" />
<meta name="appilot:token-endpoint" content="/appilot/widget-token" />
  • appilot:widget-key is your publishable widget key (the same one the widget uses; it is safe to put in HTML).
  • appilot:token-endpoint is a URL on your own origin that returns a host-signed widget token for the currently signed-in user. It must be same-origin with the page; the extension rejects a cross-origin endpoint.

You may also add <meta name="appilot:external-id" content="user-123" /> as a display hint, but it is never used as the source of truth.

2. Expose the token endpoint (your backend)​

The token endpoint mints a host-signed widget token using your server secret (never shipped to the browser). This is the same federation handshake the widget uses:

GET /appilot/widget-token            (your backend, protected by your session)
  -> calls Appilot POST /widget/token
       headers: X-Widget-Secret: <your server secret>
       body:    { "externalId": "<your stable user id>", "email": "<optional>" }
  -> returns { "token": "<host-signed widget token>" }

Return the token as JSON: { "token": "..." }. The endpoint is protected by your app's own session (the extension fetches it with credentials), so only the signed-in user can obtain their own token.

3. The user confirms (in the extension)​

When the extension panel detects the declaration and the user is signed in to Appilot, it shows a one-time "Link your account" banner. On confirm, the extension fetches the token from your endpoint and sends it to Appilot, which verifies the signature and binds the accounts. After that, the banner does not appear again on your site for that user.

Notes​

  • Linking is sticky: once a user's app identity is linked to an Appilot account, it is not silently re-pointed to a different account.
  • Linking does not change who pays. Widget usage on your site is billed to your organization; the user's personal plan is untouched unless they use the extension off your site.
  • Account linkage requires the federation server secret. See your widget key's secret in the Backoffice (it is shown once at creation).