Identity payload
What to send so UserHero can authenticate your user and unify their tickets.
Identity payload
The identity payload is the small JSON object you sign and pass to the SDK. UserHero uses it to identify the customer and route their tickets to the right profile.
Required fields
| Field | Type | Required | Description |
|---|---|---|---|
expiresAt | number (Unix seconds) | Yes | When the signed payload should stop being accepted. Use a short window (a few minutes from now). |
email or phone or externalUserId | string | At least one | UserHero needs at least one identifier to attach the customer profile. |
Recommended fields
| Field | Type | Description |
|---|---|---|
externalUserId | string | Your application's user id. Strongly recommended — it lets UserHero merge feedback from your widget, email, and portal under a single record. |
email | string | Customer's email. Used for notifications. |
phone | string | Customer's phone (E.164 format). |
name | string | Display name shown in your UserHero dashboard. |
company | string | Customer's company. |
locale | string | en or es. Overrides the project default. |
Unifying with the JavaScript widget
If you already use the UserHero widget on the same site, pass the same value for externalUserId here as you pass for userId in UserHero.setMetadata({ userId }). Both surfaces will resolve to the same customer profile, so an agent sees the user's full history in one place.
// Widget
UserHero.setMetadata({ userId: user.id, email: user.email });
// Embedded Portal — same id, signed server-side
{
externalUserId: user.id,
email: user.email,
expiresAt: Math.floor(Date.now() / 1000) + 300,
}See JavaScript SDK metadata for more on the widget side.
Trust model
UserHero treats identifiers from the embedded portal as verified because the payload is signed with your project secret server-side. Identifiers sent from the browser widget are treated as unverified until a verified surface confirms them — this prevents a tampered page from claiming another user's identity.
Example payload
{
"externalUserId": "usr_8f2k9d",
"email": "lisa@example.com",
"name": "Lisa Chen",
"company": "Acme Co.",
"locale": "en",
"expiresAt": 1735693200
}