---
title: Identity and traits
description: Associate visitors with account IDs, update traits, verify identity and reset on sign-out.
package: "@userreason/js"
version: "0.5.4"
url: https://docs.userreason.com/sdk/identity/
updated: 2026-10-16
---

# Identity and traits

The SDK starts anonymously by default. Identify the visitor after your application's authentication succeeds so targeting and responses can be associated with your account ID.

## Restoring a signed-in session

When authentication is asynchronous, set `waitForIdentity: true` in your browser entry. The SDK waits for your application's current account before opening its first session or evaluating page-load surveys. The server can then exclude surveys that account already completed, without briefly displaying an anonymous survey.

```ts
import UserReason from '@userreason/js';

UserReason.init({ siteId: 'YOUR_SITE_ID', waitForIdentity: true });

// In your application's successful authentication callback:
UserReason.identify('customer-123', { plan: 'pro' });
await UserReason.ready();
```

Resolve authentication before awaiting `ready()`, `event()`, `show()` or `refresh()`; these calls also wait for identity. `reset()` cancels pending work and waits for the next `identify()` too, so sign-out and expired-login recovery cannot show an anonymous survey. An authentication failure leaves prompting paused until your app identifies. There is no timeout or automatic reuse of a previously signed-in account. The option defaults to `false` for sites that should survey immediately as anonymous.

## identify(userId, traits?, identityToken?): void

```ts
import UserReason from '@userreason/js';

UserReason.identify('customer-123', { plan: 'pro', teamSize: 8 });
await UserReason.ready();
```

| Parameter | Meaning |
| - | - |
| `userId` | Your stable account ID; a nonempty string of at most 240 characters. An email address is unnecessary if you have an internal ID. |
| `traits` | Optional scalar values: strings, finite numbers, booleans or `null`. Nested objects and arrays are unsupported. |
| `identityToken` | Optional short-lived assertion from your backend for verified ownership and traits. |

In managed mode, trait keys follow the event-name identifier format, with at most 128 keys and 4000 characters per string value.

The first `identify()` call connects the anonymous visitor to the account while preserving any open survey, typed answers, voice recording and pending submission. Calling `identify()` again for the **same ID** merges new traits and also preserves the survey. Switching between **identified accounts** replaces the traits, closes the current survey and starts a session for the new account. `identify()` itself returns immediately; await `ready()` when subsequent work needs the updated session.

An open survey retains the session that admitted it for display, dictation and response requests. The server links its anonymous feedback to the identified person without changing the original evidence or upgrading its verification. Later events and surveys use the identified session. Use `waitForIdentity` when the first survey must respect a returning account's history; preserving an already admitted anonymous survey cannot retroactively check that history before display.

## Verified identity

A browser account ID is attribution, not proof that the visitor owns that account. Browser traits such as `plan` are also unverified. Use `verified_trait` audience conditions when eligibility must depend on trusted data.

Your authenticated backend must derive the account ID and trusted traits from its own session and data, then obtain a short-lived UserReason identity assertion with permission for that site. The management identity operation returns `identity_token` and `expires_in` (60 seconds). Send only the assertion to the browser; keep management credentials on your server.

Pass the assertion as the third argument to `identify()`, or configure `getIdentityToken` at initialization to obtain a fresh one when the SDK creates or renews its session. The callback may be asynchronous. A token supplied once through `identityToken` is not a permanent credential.

An identity assertion verifies identity and traits. [Event proofs](https://docs.userreason.com/sdk/events/index.md#verified-events) verify a particular occurrence and its properties.

## reset(): void

Call after sign-out:

```ts
import UserReason from '@userreason/js';

UserReason.reset();
await UserReason.ready();
```

This closes the survey, aborts pending work, and clears the stored session, event summaries and traits. By default it starts a fresh anonymous visitor. With `waitForIdentity: true`, it waits for the next `identify()` instead. It does not restore a previous anonymous identity or delete responses and frequency history held on the server.

Use `identify()` when switching directly between signed-in accounts. Use [destroy()](https://docs.userreason.com/sdk/initialization/index.md#destroy-void) when tearing down the whole integration.