Quick start

Get the Embedded Portal running in your app in a few minutes.

1. Enable the portal in UserHero

Open your project in the UserHero dashboard and go to Settings → Embedded Portal.

1. Toggle Enable Embedded Portal on.
2. Add the origins where the portal will load (e.g. https://app.example.com). Only HTTPS origins are accepted.
3. Pick your default locale, theme, and brand colors.
4. Click Save.

When you enable the portal for the first time, UserHero generates an HMAC secret. Click Reveal once and copy it to your secrets manager — for security reasons it is only shown once. You can rotate it any time from the same screen.

2. Sign your user's identity on the server

When a logged-in user lands on a page that should show the portal, your server signs a small JSON payload with the HMAC secret and returns it to the browser.

A minimal payload looks like:

{
    "externalUserId": "usr_8f2k9d",
    "email": "lisa@example.com",
    "expiresAt": 1735693200
}

expiresAt is a Unix timestamp in seconds. UserHero rejects payloads older than a few minutes, so generate a fresh payload on each page load.

See HMAC signing examples for code in Node, Python, Ruby, PHP, and Go.

3. Install the snippet

Drop this snippet into your HTML, just before the closing </body> tag. Replace YOUR_PUBLIC_KEY with the key shown in your project settings, and inject userPayload and userHmac from your server.

<script>
    (function () {
        window.UserHeroQueue = window.UserHeroQueue || [];
        window.UserHeroQueue.push([
            'init',
            {
                publicKey: 'YOUR_PUBLIC_KEY',
                user: {
                    externalUserId: 'usr_8f2k9d',
                    email: 'lisa@example.com',
                    expiresAt: 1735693200,
                },
                userHmac: 'SERVER_GENERATED_HMAC',
                launcher: 'button',
            },
        ]);
    })();
</script>
<script src="https://userhero.co/portal.js" async></script>

That's it. A floating support button appears in the bottom-right corner. Clicking it opens the portal panel; your user can immediately submit a ticket.

Render server-side, not client-side

Always generate the HMAC on your server. Never expose the HMAC secret in your frontend code, mobile bundle, or any client-side environment — anyone who reads it can impersonate your users.

Next

• Identity payload reference
• SDK API reference
• Theming