Identity verification

Identity verification requires a valid signed token from your app for widget requests. Identity values that match configured claims in the token are marked as verified.

How it works

1. Open Widget settings, then find Identity verification.
2. Configure your issuer, JWKS URL, supported asymmetric signing algorithm, and claim mapping, but leave identity verification disabled.
3. Copy the displayed Audience into your token configuration.
4. Deploy the app change that passes fresh JWTs to the widget, then verify a real widget request carries the expected bearer token.
5. Enable identity verification, check that Widget settings reports no live-cache warning, then immediately test a fresh token.

Once enabled, your widget requires a valid bearer token before it will load flows. The token's issuer and audience must match your settings. The JWKS URL must publish the public key identified by the token's kid header so the signature can be verified. Select one supported asymmetric algorithm: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, or EdDSA. Tokens must use the selected algorithm and set the protected typ header to gx-widget+jwt. Each token must include an exp expiration claim. Copy the Audience shown in Widget settings instead of constructing it yourself. A successful token test reports the algorithm and token type read from the protected header after the token passes verification.

When identity verification is disabled (the default), the widget works without a token. Use that state to configure JWT verification and deploy token delivery without interrupting the live widget. Enable it only after you verify the deployed widget is sending the token. If Widget settings warns that the live cache could not be refreshed, the setting was saved but may not be active yet; open Edit, save the same configuration again, and continue only after the warning clears. Contact support if it persists. Otherwise, use the token test straight away.

Mapping verified identity claims

By default, the widget maps the JWT's sub claim to userId and its email claim to traits.email. Keep these defaults when your tokens use those standard claims.

Add a custom claim mapping when your provider uses different or nested claim names. A valid signature can still leave identity fields unresolved when the configured claims aren't present in the token.

The token test reports identity_missing when the signature is valid but none of the configured claims contain a usable user identifier. Update the claim mapping or token before treating identity verification as ready. User-specific features, such as reading conversations, reject requests that can't be tied to a verified identifier; anonymous capture can still continue.

Identity verification marks configured values from the signed token as verified. Identity resolution independently decides which identifiers and activity belong to the same profile.

Passing the token

Fetch a JWT from your auth provider and pass it to the widget. The token needs to be refreshed when your app session changes or your auth provider rotates it.

React SDK

import { useEffect } from "react";import { useGetUserFeedback } from "@getuserfeedback/react";export function GetUserFeedbackAuth({authReady,token,}: {authReady: boolean;token: string | null;}) {const client = useGetUserFeedback();useEffect(() => {if (!authReady) {return;}const operation = token? client.configure({ auth: { jwt: { token } } }): client.reset();void operation.catch((error) =>console.error("Unable to sync widget auth", error));}, [authReady, client, token]);return null;}

Mount this once inside <GetUserFeedbackProvider>. Keep authReady false while your auth provider is starting or refreshing. Set it to true only when the token is available or the user has definitively signed out.

React Native SDK

Use the same provider lifecycle in React Native:

import { useEffect } from "react";import { useGetUserFeedback } from "@getuserfeedback/react-native";export function GetUserFeedbackAuth({authReady,token,}: {authReady: boolean;token: string | null;}) {const client = useGetUserFeedback();useEffect(() => {if (!authReady) {return;}const operation = token? client.configure({ auth: { jwt: { token } } }): client.reset();void operation.catch((error) =>console.error("Unable to sync widget auth", error));}, [authReady, client, token]);return null;}

Mount this once inside <GetUserFeedbackProvider>. Keep authReady false while your auth provider is starting or refreshing. Set it to true only when the token is available or the user has definitively signed out.

JavaScript SDK

The same pattern works with any auth provider — fetch the token, pass it, and call it again when the session changes:

import { createClient } from "@getuserfeedback/sdk";const client = createClient({apiKey: "YOUR_PUBLIC_API_KEY",});const token = await yourAuthProvider.getToken();await client.configure({auth: { jwt: { token } },});

On logout, call client.reset().

Token refresh

JWT tokens expire. When a token expires and the widget needs to make a request, the request will fail with invalid_token. To avoid this, call configure() again after session changes or whenever your auth provider refreshes the token. On logout, call client.reset() so auth and identity are cleared together.

Failure behavior

When identity verification is enabled, failures are explicit:

• missing_token — no token was sent
• config_missing — the issuer, JWKS URL, or signing algorithm is missing or unusable, so identity verification isn't fully configured yet
• config_invalid — saved identity-verification settings are malformed, such as an invalid claim mapping or unsupported signing algorithm; open Edit and save corrected values
• invalid_token — the token didn't pass verification or has expired
• identity_missing — the token is valid, but none of the configured claims produced a usable user identifier for a user-specific request

Rollout checklist

Before you roll identity verification out broadly:

1. Confirm Widget settings shows the correct issuer, JWKS URL, supported asymmetric signing algorithm, and claim mapping while identity verification is disabled.
2. Deploy the app change that fetches or mints fresh JWTs at runtime. Never embed or commit a token.
3. Verify a real request from the deployed widget carries the expected bearer token. The token test checks a sample token, not the deployed delivery path.
4. Verify the token's aud claim exactly matches the Audience shown in Widget settings. Copy this value instead of constructing it yourself.
5. Verify the token includes a future exp expiration timestamp.
6. Enable identity verification. If Widget settings warns that the live cache could not be refreshed, open Edit and save the same configuration again. Continue only after the warning clears, and contact support if it persists. Otherwise, immediately use the token test to test one success and one failure on purpose. Continue only when the success result includes at least one verified user identifier.