Skip to main content

HaapiStepper

HaapiStepper is a React UI-less component designed to handle complex, multi-step authentication HAAPI workflows. It provides a declarative way to manage HAAPI (HTTP Authentication API) flows, abstracting away the complexity of step-by-step user interactions, HTTP requests, and state transitions.

Key features​

  • Step Management: Automatically handles navigation between authentication steps
    • Automatic Redirections: Seamlessly handles server-driven redirections without exposing them to consumers
    • Automatic Polling: Polling steps are exposed to allow custom UI, but polling requests are handled automatically based on the configured interval
    • Automatic Continue Same: Continue Same responses are automatically merged with the current step without exposing them to consumers
  • State Management: Centralizes loading, error, and current step state.
  • Action Processing: Supports multiple action types (forms, links, client operations).
  • Error Handling: Provides comprehensive error state management with user feedback.
  • Type Safety: Offers full TypeScript support with strict typing.

Configuration modes​

The HaapiStepper needs a bootstrap configuration — at minimum an initialUrl (where the flow starts) and a haapi driver config — supplied in one of two ways:

  1. Served mode (default) — the stepper runs inside a server-rendered shell (e.g. the Curity HAAPI React App) that injects the config onto window.__CONFIG__ before the SPA boots. No prop is required:

    <HaapiStepper>...</HaapiStepper>

  2. Standalone (library) mode — when consumed as a library, or in any context without window.__CONFIG__, the consumer supplies the bootstrap explicitly via config.bootstrap:

    import type { HaapiStepperBootstrapConfig } from './haapi-stepper.types';

    const bootstrap: HaapiStepperBootstrapConfig = {
      initialUrl: 'https://idsvr.example.com/oauth/v2/oauth-authorize/...',
      haapi: { ... }, // HAAPI web-driver config
    };

    <HaapiStepper config={{ bootstrap }}>...</HaapiStepper>

Only one HAAPI configuration is supported per page load — the underlying driver is a process-global singleton; switching bootstrap.haapi mid-page throws (see useHaapiFetch).

Both modes can be combined with config overrides for other tunables (e.g. pollingInterval, bankIdAutostart); see HaapiStepperConfigfor the full set.

HAAPI stepper API​

Child components can access the following API via the useHaapiStepper() hook:

  • currentStep: HaapiStepperStep | null - The current authentication step (null during initial load)
  • history: HaapiStepperHistoryEntry[] - Complete history of all steps and actions taken, accessible via history[index]
  • loading: boolean - Whether the stepper is currently loading (initial load or transitioning between steps)
  • error: HaapiStepperError | null - Current error state (app errors or input validation errors)
  • nextStep: HaapiStepperAPINextStep - Function to navigate to the next step by submitting an action or link

Usage​

Wrap your application or authentication flow with this provider to enable HAAPI authentication:

Built-in HAAPI flow example using HaapiStepperStepUI:

Loading playground…

Partial customization example with custom links and default HAAPI UI components for the rest:

Loading playground…

Full customization example:

Loading playground…

Conditional customization example:

Loading playground…

Error handling​

The HaapiStepper implements a comprehensive error-handling strategy with multiple layers to ensure robust error management and an optimal user experience.

Error state management​

The HAAPI stepper manages errors according to two categories: HAAPI errors and non-HAAPI errors.

HAAPI errors​

HAAPI errors are HAAPI ProblemSteps (HAAPI flow steps of type HAAPI_PROBLEM_STEPS).

HAAPI errors are classified into two groups:

HaapiStepperError
├── app    (Unrecoverable)
│   ├── UnrecoverableProblemStep
│   ├── UnexpectedProblemStep
│   └── CompletedWithErrorStep
└── input  (Recoverable)
    ├── ValidationProblemStep
    └── IncorrectCredentialsProblemStep

AppError (Unrecoverable)

  • Description: Errors that cannot be resolved in the step (action form) where they originated, so they need to be handled at the application level (e.g., show a dedicated error page) and/or require restarting the stepper flow.
    • Like any other problem, they might include UserMessages and Links that need to be displayed to the user.
  • Types: UnrecoverableProblemStep, UnexpectedProblemStep, CompletedWithErrorStep.
  • Examples: Authentication failed, too many attempts, session mismatches.
  • Handling: Displayed as toast notifications and/or a problem step UI.

InputError (Recoverable)

  • Description: Errors that can be resolved in the step (form) where they originated.
    • They should be handled while keeping the step's UI, providing the problem's UserMessages and Links, and allowing the user to correct the input and resubmit.
  • Types: ValidationProblemStep, IncorrectCredentialsProblemStep.
  • Examples: Invalid form fields, incorrect credentials.
  • Handling: Displayed below relevant input fields for immediate correction.

HaapiStepperError interface:

interface HaapiStepperError {
  app?: AppError | null;
  input?: InputError | null;
}

HAAPI errors are provided by the useHaapiStepper hook:

const { error } = useHaapiStepper();
const { app, input } = error || {};
HAAPI error utils​

Two UI components render these errors — documented under API Reference → UI Components: HaapiStepperErrorNotifier (toast notifications for AppErrors, and optionally InputErrors) and HaapiStepperFormValidationErrorInputWrapper (field-level display of validation InputErrors).

Non-HAAPI errors​

Non-HAAPI errors are network, backend, and frontend errors that are not handled at lower levels.

The HaapiStepper throws them as JavaScript errors so they can be caught by the nearest React error boundary.