Tracking Events with Corbado Observe

Corbado Observe helps you track authentication journeys across your product so you can understand user behavior, identify drop-offs and improve conversion. It does this by capturing structured events from your application and mapping them to a clear data model. This reference describes the @corbado/observe web SDK from version 0.12 onwards. The native SDKs send into the same data model.

1. Data model entities

Entity	Description
Projects	Projects are the top-level container in the data model. Each project stores its own tracking data and events, and projects are fully isolated from each other.
Applications	Applications represent the channels of your product, for example web and native app. In most cases you keep them in one project and model them as separate applications.
Flows	Flows describe complete user journeys, such as sign-up, login or account recovery. A flow is composed of decisions and subflows and can contain nested flows.
Decisions	Decisions are the checkpoints of a journey, where a user or your system picks an authentication method or a route. In funnel analysis they create explicit nodes and can be used as filters.
Subflows	Subflows are one concrete authentication method attempt each, such as a passkey login or a password enrollment. They are auto-discovered from the step events you send.
Events	Events are the transport. Flow and decision events model flows and decisions directly. Subflow events (`subflow_started`, `subflow_step_started`, `subflow_step_finished`, `subflow_step_error`) carry a subflow type and step name and are emitted by the SDK’s operation helpers.
Users	Users in Corbado Observe mirror your own user entities. User references group multiple flows for one user and enable a per-user view on authentication behavior.
Tags	Tags are key-value pairs that add segmentation dimensions to flows.

Flows and decisions are not auto-discovered: you send their events yourself. Subflows are derived from step events. A backend classifier turns the event stream into flows, decisions and attempts, and that classified output is what the dashboards read. See Modeling for how to map your journeys onto it.

2. Event catalog

Every SDK method emits exactly one event. The wire name is what appears in debug logs, in the Observe Debugger and in the console’s events view.

Event	SDK call	Sent when
`flow_started`	`flowStarted()`	Journey entry, from one declared opener per flow
`flow_decided`	`flowDecided()`	An ambiguous entry resolves to one flow
`flow_finished`	`flowFinished()`	Success, or an explicit skip via `explicitOutcome`
`flow_auto_finished`	`flowAutoFinished()`	A nested flow’s terminal completes the parent
`flow_reset`	`flowReset()`	Rarely, an explicit restart
`flow_enriched`	`setCrossEnvironmentTransactionId()`	A cross-environment handoff
`conversion`	`conversion()`	A business conversion outside authentication
`auth_method_decision_started`	`authMethodsDecisionStarted()`	A checkpoint is presented or its options change
`auth_method_decision_finished`	`authMethodsDecisionFinished()`	A navigational choice is made
`subflow_started`	Operation helper construction	An auth method appears or starts
`subflow_step_started` / `subflow_step_finished` / `subflow_step_error`	`op.<step>.start()` / `.finished()` / `.error()`	Around the step’s application logic

There is no subflow-finished event. Each attempt’s outcome is derived from its steps.

Overview

Get started

Developer tools

Custom events reference

Tracking Events with Corbado Observe

1. Data model entities

2. Event catalog

​1. Data model entities

​2. Event catalog

1. Data model entities

2. Event catalog