Subflows with Corbado Observe

Subflows are the concrete building blocks inside a flow. Each subflow is one authentication method attempt, for example a passkey login, a password enrollment or an email OTP verification. Subflows are auto-discovered by Corbado Observe from the step events you send.

Install and set up the Corbado Observe SDK, including your first tracked event, in Custom events. This page explains the subflow concept and documents all available subflow types.

1. How subflows work

On SDK level, every subflow type has an operation helper on the tracker, for example passkeyLoginFullOperation(). The helper stamps the subflow type and step names for you, so your code only wraps the application logic of each step.

1.1 Start

Creating the helper emits subflow_started: the attempt begins. Construction always emits the start, even without an input field or configuration. Do not add a manual subflowStart() on top of it. Repeated starts of the same subflow type with nothing in between are merged. A different, known spec type starts a new attempt. When to create the helper depends on how the method is engaged:

Method kind	Examples	Create the helper when
Input-bound	password, OTP, identifier, provide-data	The input renders. The field is the attempt surface, and the helper captures interaction on it when you pass `inputHtmlField`.
Action-bound	passkey button, social button, app confirmation	The action happens. A visible button is not an attempt. A helper created for a button nobody pressed classifies as an attempt with no follow-up, which is an error.

Older SDK versions used a separate subflow_trigger event to mark the moment of interaction. It is deprecated and carries no classification value. Interaction is read from the first step and from the bound input field.

1.2 Steps

Each step is one phase of the attempt, identified by its step name, and tracked with three events:

Event	SDK call	Meaning
`subflow_step_started`	`op.<step>.start(data)`	The step began.
`subflow_step_finished`	`op.<step>.finished(data)`	The step completed successfully.
`subflow_step_error`	`op.<step>.error(err)` or `op.<step>.errorTyped({ code })`	The step failed.

Every helper defines its steps (section 3). Custom steps beyond the predefined ones are available through op.customStep("my-step"). Never finish a subflow. There is no subflow-finished event. The classifier derives each attempt’s outcome from its steps. The outcome-bearing step is postResponse for almost every subflow (exchangeCode for social login, ceremony for app confirmation). Track it always. Earlier steps are enrichment you may skip when the effort outweighs the value, with one exception: the WebAuthn ceremony steps of the passkey subflows. Track those whenever passkeys are in play, because ceremony start, finish and error power all passkey analytics and none of it is recoverable from postResponse alone. A completed ceremony without a postResponse still classifies as incomplete, because only the backend confirmation proves the method worked. On failure, call .error() on the step that failed and stop. A retry is simply a new sequence of step events.

1.3 Spec types

explicitSpecType distinguishes variants of one subflow type, for example a passkey login with a known identifier from one without. Supply it in the helper’s config whenever it is known. If it only becomes known mid-attempt, send it on a later step’s start data. The last spec type wins.

Requirement	Subflow types
Required. The classifier drops an attempt without a spec type on any of its events.	passkey-login, passkey-enrollment, password-enrollment, provide-data, email-link, social-login
Defaulted when absent.	email-otp and sms-otp assume the login variant, password-login assumes `password-known-identifier`, provide-identifier assumes `email`, app-confirmation assumes `qr-code`.

1.4 Errors

Error tracking is an optional investment. Classification never depends on it: an attempt that just stops already classifies as incomplete, and an explicit step error is a different, more diagnostic outcome. The backend groups every reported error by its exact signature (subflow type, step, code, message, spec type) into error flavours that are then curated into named errors with impact analysis. That yields four rules:

Platform errors go in raw. For failures the browser or operating system produces, such as a WebAuthn exception, pass the caught exception to .error(e). The platform’s own vocabulary is bounded and groups well.
Your own errors deserve a deliberate shape. For failures from your API, pass a plain { code, message } object: a code naming what the client observed (invalid_password, invalid_otp, http_error), reused wherever the same observation recurs, and the server’s raw error label as the message. Where a helper predefines typed codes, prefer errorTyped() for the compile-time check.
Keep volatile tokens out of messages. Request IDs, timestamps and user data fragment the grouping.
No fallback codes. A response you cannot classify is neither success nor failure. Leave the step open and it classifies as incomplete.

User cancellation is an error on the step that observed it: a dismissed passkey prompt is a ceremony error with the raw browser error. The exception is an auto-offered method torn down because the user proceeded with another, for example a Conditional UI request aborted by a password submit. That is not an error.

op.postResponse.start({});
const body = await submitPassword(password);
if (body.rejected) {
  op.postResponse.error({ code: "invalid_password", message: body.errorLabel });
  // or, compile-time checked where the helper types the code:
  op.postResponse.errorTyped({ code: "invalid_password" });
}

1.5 Cleanup

Input-bound helpers and the passkey helpers hold event listeners. Call op.destroy() when the surface unmounts. A “Sign in with passkey” button after the identifier is known:

#	Event	Step	Description
1	`subflow_started`		The user clicks the button. The helper is created with `passkey-known-identifier`.
2	`subflow_step_started`	`get-options`	Assertion options are requested from your server.
3	`subflow_step_finished`	`get-options`	The server returns them.
4	`subflow_step_started`	`ceremony`	The browser WebAuthn ceremony begins.
5	`subflow_step_finished`	`ceremony`	The user completes it. A cancellation is a `subflow_step_error` here instead.
6	`subflow_step_started`	`post-response`	The assertion is sent to your server.
7	`subflow_step_finished`	`post-response`	The server confirms the login. The attempt is complete.

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

const handlePasskeyLogin = async (email: string) => {
  const op = getTracker().passkeyLoginFullOperation({ explicitSpecType: "passkey-known-identifier" });

  let options, response;
  try {
    op.getOptions.start({});
    options = await fetchAssertionOptions(email);
    op.getOptions.finished({ assertionOptions: JSON.stringify(options) });
  } catch (e) {
    op.getOptions.error(e);
    return;
  }

  try {
    op.ceremony.start({});
    response = await startWebAuthnAuthentication(options);
    op.ceremony.finished({ assertionResponse: JSON.stringify(response) });
  } catch (e) {
    op.ceremony.error(e); // also when the user cancels the prompt
    return;
  }

  try {
    op.postResponse.start({});
    const result = await verifyOnServer(response);
    op.postResponse.finished({}, { userReference: { userId: result.userId } });
  } catch (e) {
    op.postResponse.error(e);
  }
};

The passkey steps carry the WebAuthn payloads as JSON strings. For login, getOptions.finished takes assertionOptions and ceremony.finished takes assertionResponse. For enrollment, the same steps take attestationOptions and attestationResponse, and the enrollment ceremony.start additionally requires mediation ("conditional", "optional" or "required").

3. Subflow types

Helper signatures can move between releases. Read the installed package’s type definitions before applying a recipe.

Helper on the tracker	Subflow type	Steps	Spec types
`provideIdentifierOperationFull(config?)`	`provide-identifier` (plus passkey Conditional UI)	`provideIdentifier.clientValidation`, `provideIdentifier.postResponse`; `cui.getOptions`, `cui.ceremony`, `cui.postResponse`	`email`, `phone`; CUI: `passkey-cui`
`passkeyLoginFullOperation(config?)`	`passkey-login`	`getOptions`, `ceremony`, `postResponse`	`passkey-known-identifier`, `passkey-known-identifier-auto`, `passkey-no-identifier`, `passkey-no-identifier-auto`, `passkey-cui`, `passkey-immediate`
`passkeyEnrollmentFullOperation(config?)`	`passkey-enrollment`	`getOptions`, `ceremony`, `postResponse`	`conditional`, `auto`, `manual`; legacy `conditional-auto-manual`, `auto-manual`
`passwordLoginFullOperation(config?)`	`password-login`	`clientValidation`, `postResponse`; `cui.getOptions`, `cui.ceremony`, `cui.postResponse`	`password-known-identifier`, `password-with-identifier`; CUI: `passkey-cui`
`passwordEnrollmentFullOperation(config?)`	`password-enrollment`	`clientValidation`, `postResponse`	`password-set`, `password-reset`
`emailOtpOperationFull(config?)`	`email-otp`	`send`, `postResponse`, `resend`	`email-otp-login`, `email-otp-enrollment`
`smsOtpOperationFull(config?)`	`sms-otp`	`postResponse`, `resend`	`sms-otp-login`, `sms-otp-enrollment`
`emailLinkOperationFull(config?)`	`email-link`	`send`, `postResponse`, `resend`	`email-link-login`, `email-link-enrollment`
`socialLoginOperationFull(config?)`	`social-login`	`getRedirectUrl`, `exchangeCode`	`pre-identifier`, `post-identifier`
`provideDataOperationFull(config?)`	`provide-data`	`clientValidation`, `postResponse`	`signup`, `login`, `recovery`, `enrollment`
`appConfirmationOperationFull(config?)`	`app-confirmation`	`ceremony`, `retry`, `postResponse`	`qr-code`
`captchaOperationFull(config?)`	`captcha`	`ceremony`, `postResponse`	`visible`, `invisible`

Every config accepts explicitSpecType. There is no autoStart option: create the helper when the attempt should begin. The input-bound helpers additionally accept inputHtmlField for input tracking; it does not control whether the attempt starts. For a subflow type without a helper, such as totp, use the low-level tracker methods trackSubflowStarted(), trackSubflowStepStarted(), trackSubflowStepFinished() and trackSubflowStepError() with the same shape.

3.1 Provide identifier

Tracks when users enter and submit their identifier, typically an email address. Bind the helper to the identifier input so the SDK captures interaction on it. Passkey Conditional UI (autofill) is bound to the same input field, so its events are tracked through this helper’s cui steps. Conditional UI is not a passkey-login attempt: it resolves the same identifier-email option as a typed identifier, and a Conditional UI request torn down because the user submitted the identifier is neutral, not an error.

Step	Description
`provideIdentifier.clientValidation`	Optional client-side validation of the identifier.
`provideIdentifier.postResponse`	Server-side identifier check: does the user exist, which methods are available.
`cui.getOptions`	Assertion options for the Conditional UI request.
`cui.ceremony`	The pending autofill ceremony. Finishes when the user picks a passkey.
`cui.postResponse`	Server verification of the Conditional UI assertion.

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

const identifierInput = document.getElementById("email") as HTMLInputElement;
const op = getTracker().provideIdentifierOperationFull({
  inputHtmlField: identifierInput,
  explicitSpecType: "email",
});

// Conditional UI, started when the identifier surface renders.
const startConditionalUI = async () => {
  let options;
  try {
    op.cui.getOptions.start({ explicitSpecType: "passkey-cui" });
    options = await fetchConditionalUIOptions();
    op.cui.getOptions.finished({ assertionOptions: JSON.stringify(options) });
  } catch (e) {
    op.cui.getOptions.error(e);
    return;
  }

  op.cui.ceremony.start({});
  try {
    const response = await startWebAuthnAuthentication(options, { useBrowserAutofill: true });
    op.cui.ceremony.finished({ assertionResponse: JSON.stringify(response) });

    op.cui.postResponse.start({});
    const result = await verifyOnServer(response);
    op.cui.postResponse.finished({}, { userReference: { userId: result.userId } });
  } catch (e) {
    // Torn down because the user submitted the identifier or left: not an error.
    if (!displacedByUser) op.cui.ceremony.error(e);
  }
};

// Manual path: the user submits the form.
const handleIdentifierSubmit = async (email: string) => {
  op.provideIdentifier.postResponse.start({});
  try {
    const result = await checkUserOnServer(email);
    op.provideIdentifier.postResponse.finished({}, { userReference: { userId: result.userId } });
  } catch (e) {
    op.provideIdentifier.postResponse.error(e);
  }
};

// When the component unmounts.
op.destroy();

Tracks passkey sign-in attempts where the WebAuthn ceremony is started explicitly, by a button or by your code. Conditional UI on the identifier field belongs to provide identifier instead.

Spec type	Description
`passkey-known-identifier`	The identifier is known and the user clicks a passkey button. The server can scope the allowed credentials.
`passkey-known-identifier-auto`	Same, but your code starts the ceremony automatically after the identifier is known.
`passkey-no-identifier`	No identifier is known. The user clicks a discoverable passkey button.
`passkey-no-identifier-auto`	Same, but started automatically by your code.
`passkey-cui`	Conditional UI. Prefer the provide-identifier or password-login helper for this.
`passkey-immediate`	Immediate mediation (`mediation: "immediate"`): the browser offers a passkey prompt right when the login page loads. Runs before any decision and resolves no option.

See section 2 for the button example. Immediate mediation looks the same with explicitSpecType: "passkey-immediate" and mediation: "immediate" on the WebAuthn call. If the ceremony fails, continue with your regular login and start Conditional UI on the identifier field.

3.3 Passkey enrollment

Tracks passkey registration, for example after login or during sign-up.

Spec type	Description
`conditional-auto-manual`	Your code first attempts conditional (auto-register) enrollment, falls back to a regular prompt and finally lets the user trigger it manually.
`auto-manual`	Your code auto-triggers the enrollment prompt, with a manual fallback.
`manual`	The user explicitly triggers enrollment, for example by clicking “Create passkey”.

The ceremony.start data requires mediation, which tells Observe how the credential manager was invoked.

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

const handleManualEnrollment = async (userId: string) => {
  const op = getTracker().passkeyEnrollmentFullOperation({ explicitSpecType: "manual" });

  let options, response;
  try {
    op.getOptions.start({});
    options = await fetchAttestationOptions(userId);
    op.getOptions.finished({ attestationOptions: JSON.stringify(options) });
  } catch (e) {
    op.getOptions.error(e);
    return;
  }

  try {
    op.ceremony.start({ mediation: "required" });
    response = await startWebAuthnRegistration(options);
    op.ceremony.finished({ attestationResponse: JSON.stringify(response) });
  } catch (e) {
    op.ceremony.error(e);
    return;
  }

  try {
    op.postResponse.start({});
    await verifyOnServer(response);
    op.postResponse.finished({}, { userReference: { userId } });
  } catch (e) {
    op.postResponse.error(e);
  }
};

For conditional-auto-manual, run the same steps with mediation: "conditional" first. If the conditional ceremony errors, a regular prompt is a new sequence of step events on the same helper with mediation: "required". explicitSpecType also accepts conditional for a silent conditional-create attempt and auto for an automatically triggered regular prompt. Use a new operation for each attempt when using these values; keep manual for a user-triggered attempt. The combined values above remain supported for existing integrations that model one offer across its fallbacks. The enrollment helper’s configuration also accepts ignoreAsInteraction: true for a programmatic start without a user gesture or visible surface, such as a conditional attempt. It marks the emitted start as non-interactive; it does not suppress the operation’s later step events. subflowStart() and trigger() data also accept this flag. Do not apply it to a user-triggered start. Tracks password-based login attempts. Bind the helper to the password input so the SDK captures interaction on it. Create it when the password field renders.

Spec type	Description
`password-known-identifier`	The identifier was submitted in a previous step. Only the password is entered on this screen.
`password-with-identifier`	Identifier and password are entered together on one screen.

Typed error codes: invalid_password, user_not_found, account_locked. When identifier and password share one screen, Conditional UI is bound to that screen too. This helper therefore carries the same cui steps as provide identifier. Conditional UI fired through it resolves the passkey-login-cui option.

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

let passwordOp: PasswordLoginOperationFull;

// When the login component mounts. Returns the cleanup for unmount.
const handleOnLoad = () => {
  const passwordInput = document.getElementById("password") as HTMLInputElement;
  passwordOp = getTracker().passwordLoginFullOperation({
    inputHtmlField: passwordInput,
    explicitSpecType: "password-known-identifier",
  });
  return () => passwordOp.destroy();
};

const handlePasswordSubmit = async (email: string, password: string) => {
  passwordOp.postResponse.start({});
  const result = await verifyPasswordOnServer(email, password);
  if (result.ok) {
    passwordOp.postResponse.finished({}, { userReference: { userId: result.userId } });
  } else {
    passwordOp.postResponse.errorTyped({ code: "invalid_password" });
  }
};

3.5 Password enrollment

Tracks password creation during sign-up (password-set) or a password reset during recovery (password-reset). Bind it to the new-password input. Typed error code: requirements_not_fulfilled.

3.6 Email OTP and SMS OTP

Track one-time-password verification. Steps: send (email only), postResponse for the code the user submitted, resend when a new code is requested. Spec types distinguish the login variant from the enrollment variant, for example email verification during sign-up.

3.7 Email link

Tracks sign-in or verification through a link sent by email. Steps: send, postResponse for the token from the clicked link, resend. Email links often continue in a different tab, browser or device. Pass the same crossEnvironmentTransactionID in the user reference of the send step and the later postResponse step so both sides are correlated. Generate one or reuse an existing transaction ID from your system. It does not replace userId, which you still provide as soon as it is known. See the recovery example. Tracks authentication with social identity providers. Steps: getRedirectUrl when your app initiates the OAuth redirect, exchangeCode when the user returns and the code is exchanged. exchangeCode is the outcome-bearing step. Spec types: pre-identifier when the button is shown before any identifier, post-identifier when it is offered after one.

3.9 Provide data

Covers form fields that request user data but map to no deeper subflow concept, such as name, address, birth date or bank details. One screen, one provide-data subflow bound to the most important field. Pass fieldName on postResponse.start for the semantic name of what is collected. The spec type names the surrounding flow.

3.10 App confirmation

Tracks a login approved in another app, for example by scanning a QR code. ceremony is the approval and the outcome-bearing step, with typed error codes declined and expired. retry covers a re-issued code.

3.11 Captcha

Tracks a captcha challenge inside an authentication journey. Steps: ceremony for the challenge, postResponse for the server-side check. Spec types visible and invisible.

4. Parallel subflows

Parallel subflows are fine as long as only one can plausibly receive interaction at a time: a password field plus a passkey button on one screen is classifiable. A large form where several tracked fields are filled and submitted together is not. Model the simplified version and track only the most important field, for example the password field on a sign-up form.

5. Next steps

Continue with Users to link attempts to your user entities.
Read Modeling for when to create helpers and a journey catalog.

Overview

Get started

Developer tools

Custom events reference

Subflows with Corbado Observe

1. How subflows work

1.1 Start

1.2 Steps

1.3 Spec types

1.4 Errors

1.5 Cleanup

3. Subflow types

3.1 Provide identifier

3.3 Passkey enrollment

3.5 Password enrollment

3.6 Email OTP and SMS OTP

3.7 Email link

3.9 Provide data

3.10 App confirmation

3.11 Captcha

4. Parallel subflows

5. Next steps

​1. How subflows work

​1.1 Start

​1.2 Steps

​1.3 Spec types

​1.4 Errors

​1.5 Cleanup

​2. Example: passkey login

​3. Subflow types

​3.1 Provide identifier

​3.2 Passkey login

​3.3 Passkey enrollment

​3.4 Password login

​3.5 Password enrollment

​3.6 Email OTP and SMS OTP

​3.7 Email link

​3.8 Social login

​3.9 Provide data

​3.10 App confirmation

​3.11 Captcha

​4. Parallel subflows

​5. Next steps

1. How subflows work

1.1 Start

1.2 Steps

1.3 Spec types

1.4 Errors

1.5 Cleanup

2. Example: passkey login

3. Subflow types

3.1 Provide identifier

3.2 Passkey login

3.3 Passkey enrollment

3.4 Password login

3.5 Password enrollment

3.6 Email OTP and SMS OTP

3.7 Email link

3.8 Social login

3.9 Provide data

3.10 App confirmation

3.11 Captcha

4. Parallel subflows

5. Next steps