Authentication

Secure authentication for Reach

Reach uses JSON Web Tokens (JWT) for secure authentication. Each token links a user in your system to a user in Reach.

Please reach out to [e-mail] to get a Shared Secret for your platform in order to generate JWT tokens.

If your app enforces security headers like Content Security Policy (CSP) or Cross-Origin Opener Policy (COOP), see Security Headers (CSP & COOP) for required configurations.

Tenant Scoped JWT Token Requirements

Sign your tenant-scoped token with your Shared Secret using HS256. It must include the following fields:

Field	Description	Required
email	User’s email address	Yes
name	User’s display name	Yes
externalId	Your system’s unique ID for this user, as a string	Yes
tenantExternalId	Your system’s ID for the user’s business	Yes
partnerId	Your unique vertical saas platform identifier provided by Reach	Yes
iat	Issued at time (in seconds since epoch)	Yes
exp	Expiration time (in seconds since epoch)	Yes
type	Set to tenant to mark the token as tenant-scoped	No

Never expose your Shared Secret on the client side. JWT generation must always be handled server-side.

Identifying the End User

externalId is how Reach tells your users apart. Each externalId becomes a distinct user under that tenant, so activity in the embedded UI can be attributed to a person rather than to the business as a whole.

For that to work, externalId must be:

• A string. If your user IDs are numbers, convert them: String(user.id).
• Stable. Send the same value every time you mint a token for that person.
• Unique within the tenant. Two people in the same business must never share one.

If externalId is missing, or is anything other than a string, every request from that tenant resolves to one shared user. The token still authenticates and no error is returned — you simply lose per-user attribution. Sending a numeric ID such as externalId: 12345 is the most common cause.

email and name are recorded the first time Reach sees a given externalId, and are not updated by later tokens.

Users are scoped to the tenant they were seen under. The same externalId sent with two different tenantExternalId values is two separate users, and no user identity is shared across tenants.

Reach stores the externalId, email, and name you send for each user.

Token Lifecycle

We recommend tokens expire after 1 hour (3600 seconds). The Reach SDK handles token expiration by calling your onReauthRequested callback when a token expires.

For a full server side example of how to generate JWT Tokens that are compatible with Reach please see the examples section here.