Skip to main content
In Corbado Observe, users are a mirror of your own user entities. Corbado Observe does not create an independent user model for authentication logic. Instead, it links events to your users so you can analyze authentication per user across multiple flows.

​
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: A user-facing identifier (for example email)
  • crossEnvironmentTransactionID: Optional correlation ID for cross-device or email-link flows
Use at least one stable identifier (userId is recommended). Send both userId and identifier whenever available.
User reference fields are limited to userId, identifier, and crossEnvironmentTransactionID.

​
3. Send user references from the SDK

In the Corbado Observe SDK, every event supports an optional user reference. You can pass user references with flow events, subflow step events, and any other tracking call. The most common points to send user references are:
  • When a login or signup flow completes — this covers all successful authentication flows. Pass the user reference in flowFinished().
  • During a flow when the user identity becomes known — typically after the provide-identifier subflow step completes and your backend resolves the identifier to a user. Pass the user reference in the corresponding subflow step event.
  • When an enrollment flow starts — before a user can enroll a new authentication method (for example a passkey), their identity must already be known. Pass the user reference in the first subflow step event of the enrollment.
Corbado Observe SDK installation and setup are explained in Getting started.
import { init, getTracker } from "@corbado/observe";

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

// Most common: pass user reference when a flow finishes
getTracker().flowFinished({
  flowName: "login",
  userId: "usr_12345",
  identifier: "max@example.com",
});

​
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)
  • Add identifier when it improves debugging or 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.