Send User References to Corbado Observe

User references connect Observe flows to the user IDs your authentication system supplies. This page explains how to send those references from the SDK. For the meaning of a user link, failed attempts across devices and identifier search, start with Users and identifiers.

1. Why user mapping matters

Adding user information to events helps you:

Group multiple flows (for example login retries and recovery) under the same user
Analyze authentication behavior in a per-user view
Connect anonymous pre-login events with known users as soon as identity is available

User references are strongly recommended because they power reliable per-user analysis in Corbado Observe.

2. User reference model

Corbado Observe supports these user reference fields:

userId: Your stable internal user ID
identifier: Deprecated. A flow-level user-facing reference that existing integrations can keep sending; new code captures identifiers on the provide-identifier step instead
crossEnvironmentTransactionID: Optional correlation ID for cross-device or email-link flows

Prefer your stable userId for user enrichment. Capture submitted emails, phone numbers and usernames separately on the provide-identifier step so each submission remains searchable, including typos, changes and failures. User reference fields are limited to userId, identifier and crossEnvironmentTransactionID.

3. Send user references from the SDK

Call setUser() on the tracker as soon as the identity is known, while the flow is open. The SDK records it as a flow_enriched event on that flow, and the classifier attaches it to the flow and to every attempt inside it. Call it before flowFinished(). One call per identity observation is enough; the latest reference per flow wins. Choose the point at which your authentication system supplies the reference:

When the host confirms the user: Send the userId with the login result, before finishing the flow.
When an enrollment flow starts: The user is already logged in, so the reference is known at flowStarted().
When the host resolves an account before authentication: An early user reference can identify the account being targeted. Its presence alone does not establish who made the attempt or prove ownership of a submitted identifier.

Failed attempts remain searchable through their captured identifier submissions even without a confirmed user. Later user enrichment retains those submissions. A qualified identifier-to-user link is a separate relationship; see the evidence rule. Passing userId or identifier inside flowFinished(), flowAutoFinished(), conversion() or the userReference step option still works and is deprecated. Use setUser() in new code. For SDK installation and setup, see Integrate custom events.

import { init, getTracker } from "@corbado/observe";

init({
  projectId: "<ProjectID>",
  apiBaseUrl: "<APIBaseURL>",
});

getTracker().flowStarted({ flowName: "login" });
// ... your authentication system confirms the login
getTracker().setUser({ userId: "usr_12345" });
getTracker().flowFinished({ flowName: "login" });

<script>
  Corbado.init({
    projectId: "<ProjectID>",
    apiBaseUrl: "<APIBaseURL>",
  });

  Corbado.get().flowStarted({ flowName: "login" });
  // ... your authentication system confirms the login
  Corbado.get().setUser({ userId: "usr_12345" });
  Corbado.get().flowFinished({ flowName: "login" });
</script>

4. Best practices

Prefer your immutable internal user ID for userId (or a hash of it if you prefer not to expose your user IDs)
Capture identifiers per submission for debugging and support workflows
Send the same user reference consistently across all relevant auth events
Do not use tags for identity mapping; use tags for segmentation

5. Next steps

Continue with Tags to add optional segmentation metadata.
Continue with Flows to model complete user journeys.

Overview

Get started

Custom events

Developer tools

Data access

Security & compliance

Custom events reference

Send User References to Corbado Observe

1. Why user mapping matters

2. User reference model

3. Send user references from the SDK

4. Best practices

5. Next steps

​1. Why user mapping matters

​2. User reference model

​3. Send user references from the SDK

​4. Best practices

​5. Next steps

1. Why user mapping matters

2. User reference model

3. Send user references from the SDK

4. Best practices

5. Next steps