Customer identity
Use signed customer identities, anonymous visitors, or guest email capture.
Choose an identity
Without an identify call, BTX creates a random anonymous visitor. Use that mode for website visitors, or let guests enter email through the SDK. To connect a signed-in customer to their account, use the stable ID your backend already trusts and a server-signed identity token. Email alone is never identity proof.
Use the same canonical account ID as your iOS integration when it represents the same customer in the same BTX project. Browser-local anonymous history does not automatically merge into an identified account. Anonymous histories are scoped to the browser origin and client.
// Your endpoint authenticates the app user before issuing this token.
const response = await fetch('/api/support/identity', { credentials: 'same-origin' })
if (!response.ok) throw new Error('Support identity unavailable')
const customer = await response.json()
await BTX.identify(customer) // { externalId, identityToken, name?, email? }
await BTX.messenger.open()Set up signing
A BTX project owner retrieves the Web client's identity signing key through the authenticated client management API. This operation enables identity verification for that client. The response includes data.clientId and data.signingKey; store both in your backend's secret manager. This is an administrator operation, not a request your customer browser makes.
POST https://btx.so/api/projects/PROJECT_ID/customer-app/clients/CLIENT_ID/identity-key
Authorization: Bearer YOUR_BTX_OWNER_SESSION_TOKENNew unmanaged Web clients require identity verification by default. Existing clients keep their earlier behavior until an owner enables verification; migrate their integrations before doing so. Managed Shopify clients remain on their current integration pending a separate migration.
Never put this signing key, a BTX owner session token, or server credentials in browser code. Regenerating the client's credentials invalidates the signing key and previously signed identity tokens; retrieve and install the new key after rotation.
import { createIdentityToken } from '@btx-hq/web/server'
// Call only after your server authenticates the app user.
function supportIdentity(currentUser) {
const clientId = process.env.BTX_WEB_CLIENT_ID
const signingKey = process.env.BTX_WEB_IDENTITY_SIGNING_KEY
const identityToken = createIdentityToken({
clientId, signingKey,
customer: {
externalId: currentUser.id,
name: currentUser.name,
email: currentUser.email
}
})
return { externalId: currentUser.id, identityToken }
}The token uses HS256 with issuer btx-web-identity, audience equal to the Web client ID, subject equal to the external customer ID, and integer iat/exp timestamps. Tokens may live for at most one hour. Name and email must come from your authenticated server profile; the token's signed values take precedence over browser-supplied traits. Serve identity responses with Cache-Control: no-store.
Anonymous and email guests
// A fresh anonymous identity with optional unverified contact metadata.
await BTX.identifyAnonymous({ email: 'visitor@example.com' })
// Or collect contact information in the SDK itself:
await BTX.configure({
publishableClientKey: 'cfk_your_web_client_key',
messenger: { requireEmail: true }
})
// On sign-out or account switch:
await BTX.identify(null)For a Web client in BTX, Ask for name and Ask for email are separate settings, both off by default. Enable either to ask anonymous visitors for those details before starting a thread or sending feedback. Identified customers skip the prompt. Your integration can also request these fields with messenger.requireName and messenger.requireEmail. Contact details are unverified and do not prove account identity.
The client-management switches require an updated BTX app. The integration options work directly with SDK 0.1.0.
Guest contact values stay in memory. A contact-completion marker can survive reload without persisting the actual values. Reset rotates the anonymous identity and returns to contact capture. Identifying as a new account closes SDK surfaces, discards old drafts and tears down the previous transport.
Expired or rejected identity
Obtain a fresh token from your authenticated backend on every sign-in and page load, and before the previous token expires. Call BTX.identify with the replacement token. Renewing the same account preserves open chat and feedback drafts; switching accounts clears them. Expired, tampered, cross-client and mismatched-subject tokens are rejected before customer data is written. The SDK does not store or silently renew your application's identity proof. A rejected identity needs a fresh authenticated proof; do not retry it as an anonymous request for the same account.