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, 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. You don't need an internal app ID to configure this.

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({ token }: { token: string | null }) {const client = useGetUserFeedback();useEffect(() => {if (!token) {void client.reset();return;}void client.configure({auth: { jwt: { token } },});}, [client, token]);return null;}

Mount this once inside <GetUserFeedbackProvider> and pass in the token from your auth layer.

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 — identity verification isn't configured yet
• config_invalid — the issuer, JWKS, or claim-mapping configuration has a problem
• 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 and JWKS URL while identity verification is disabled.
2. Deploy the app change that fetches or mints per-session tokens 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. 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.