API reference

The public surface of

@thunderid/javascript, as documented in its reference pages.

exportEmbedded Recovery Flow (V2)

`executeEmbeddedRecoveryFlowV2` drives a step-by-step account recovery flow (e.g., password reset) without a browser redirect.

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.payloadrequired

EmbeddedRecoveryFlowRequestV2

Flow request body

config.payload.applicationIdoptional

string

Application ID. Required for the first step

config.payload.flowTypeoptional

string

Recovery flow type (e.g., `'PASSWORD_RECOVERY'`). Required for first step

config.payload.executionIdoptional

string

Execution ID from a prior response

config.payload.actionoptional

string

Action to take at the current step

config.payload.inputsoptional

Record

Step input fields

config.payload.challengeTokenoptional

string

Challenge token from a prior step

Example

import { executeEmbeddedRecoveryFlowV2, EmbeddedRecoveryFlowStatusV2 } from '@thunderid/javascript'

// Step 1 — Initiate recovery
const step1 = await executeEmbeddedRecoveryFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    applicationId: '<your-app-id>',
    flowType: 'PASSWORD_RECOVERY',
  },
})

// Step 2 — Provide the username/email to recover
const step2 = await executeEmbeddedRecoveryFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    executionId: step1.executionId,
    inputs: {
      username: 'user@example.com',
    },
  },
})

// Step 3 — Submit the OTP/token received by email
const step3 = await executeEmbeddedRecoveryFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    executionId: step2.executionId,
    inputs: {
      otp: '123456',
    },
    challengeToken: step2.challengeToken,
  },
})

if (step3.flowStatus === EmbeddedRecoveryFlowStatusV2.Complete) {
  // Recovery complete — prompt user for new password
}

exportEmbedded Sign-In Flow (V1)

These functions implement app-native (embedded) sign-in for the V1 flow protocol. They allow you to drive the authentication sequence step-by-step without a browser redirect to the identity provider. Used internally by `ThunderIDJavaScriptClient.getAgentToken()`. :::note For new integrations, prefer the V2 flow functions, which offer a richer response model and better error handling. :::

Example

import { initializeEmbeddedSignInFlow } from '@thunderid/javascript'

const response = await initializeEmbeddedSignInFlow({
  url: 'https://localhost:8090/oauth2/authorize',
  payload: {
    response_type: 'code',
    client_id: '<your-client-id>',
    redirect_uri: 'http://localhost:3000',
    scope: 'openid profile',
    state: '<random-state>',
    code_challenge: '<pkce-code-challenge>',
    code_challenge_method: 'S256',
    response_mode: 'direct',
  },
})

exportEmbedded Sign-In Flow (V2)

`executeEmbeddedSignInFlowV2` drives a step-by-step sign-in sequence using the V2 flow protocol. It supports a richer response model with explicit error states, challenge tokens for multi-factor flows, and assertion-based completion.

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.payloadrequired

EmbeddedSignInFlowRequestV2

Flow request body

config.payload.applicationIdoptional

string

Application ID. Required for the first step

config.payload.flowTypeoptional

string

Flow type. Required for the first step (e.g., `'SIGN_IN'`)

config.payload.executionIdoptional

string

Execution ID from a prior response. Required for subsequent steps

config.payload.actionoptional

string

Action to take at the current step

config.payload.inputsoptional

Record

Step-specific input fields (e.g., credentials)

config.payload.challengeTokenoptional

string

Challenge token from a prior step (e.g., for MFA)

config.authIdoptional

string

Optional authentication context ID

Example

import { executeEmbeddedSignInFlowV2, EmbeddedSignInFlowStatusV2 } from '@thunderid/javascript'

// Step 1 — Initiate the flow
const step1 = await executeEmbeddedSignInFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    applicationId: '<your-app-id>',
    flowType: 'SIGN_IN',
  },
})

// Step 2 — Submit credentials
const step2 = await executeEmbeddedSignInFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    executionId: step1.executionId,
    inputs: {
      username: 'user@example.com',
      password: 'password123',
    },
  },
})

if (step2.flowStatus === EmbeddedSignInFlowStatusV2.Complete) {
  const assertion = step2.assertion // Use to complete the OAuth code exchange
}

exportEmbedded Sign-Up Flow (V1)

`executeEmbeddedSignUpFlow` drives a step-by-step registration flow without a browser redirect. :::note For new integrations, prefer `executeEmbeddedSignUpFlowV2`. :::

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.payloadrequired

EmbeddedFlowExecuteRequestPayload

Flow step payload

config.payload.flowTyperequired

EmbeddedFlowType

Must be `EmbeddedFlowType.Registration`

config.payload.flowIdoptional

string

Flow ID from a previous step response

config.payload.selectedAuthenticatoroptional

object

Authenticator selection (for later steps)

Example

import { executeEmbeddedSignUpFlow, EmbeddedFlowType } from '@thunderid/javascript'

const response = await executeEmbeddedSignUpFlow({
  baseUrl: 'https://localhost:8090',
  payload: {
    flowType: EmbeddedFlowType.Registration,
    // step-specific fields
  },
})

exportEmbedded Sign-Up Flow (V2)

`executeEmbeddedSignUpFlowV2` drives a step-by-step user registration flow using the V2 protocol.

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.payloadrequired

EmbeddedSignUpFlowRequestV2

Flow request body

config.payload.applicationIdoptional

string

Application ID. Required for the first step

config.payload.flowTypeoptional

string

Flow type. Required for the first step (e.g., `'REGISTRATION'`)

config.payload.executionIdoptional

string

Execution ID from a prior response

config.payload.actionoptional

string

Action to perform at the current step

config.payload.inputsoptional

Record

Registration field values

config.payload.challengeTokenoptional

string

Challenge token for verification steps

config.authIdoptional

string

Optional authentication context ID

Example

import { executeEmbeddedSignUpFlowV2, EmbeddedSignUpFlowStatusV2 } from '@thunderid/javascript'

// Step 1 — Initiate
const step1 = await executeEmbeddedSignUpFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    applicationId: '<your-app-id>',
    flowType: 'REGISTRATION',
  },
})

// Step 2 — Provide registration details
const step2 = await executeEmbeddedSignUpFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    executionId: step1.executionId,
    inputs: {
      username: 'newuser@example.com',
      password: 'SecurePass123!',
      'http://wso2.org/claims/givenname': 'New',
      'http://wso2.org/claims/lastname': 'User',
    },
  },
})

if (step2.flowStatus === EmbeddedSignUpFlowStatusV2.Complete) {
  // Registration complete — redirect or sign in
}

exportFlow Meta (V2)

`getFlowMetaV2` fetches aggregated metadata for a V2 flow context, including application branding, organization unit details, theme configuration, and available translations. Use it to pre-load everything needed to render a custom sign-in or sign-up UI.

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.typeoptional

FlowMetaType

Scope the metadata to an application (`App`) or organization unit (`Ou`)

config.idoptional

string

Application ID or OU ID, depending on `type`

config.languageoptional

string

BCP 47 language tag for the i18n metadata (e.g., `'en-US'`)

config.namespaceoptional

string

Translation namespace filter

Example

import { getFlowMetaV2, FlowMetaType } from '@thunderid/javascript'

const meta = await getFlowMetaV2({
  baseUrl: 'https://localhost:8090',
  type: FlowMetaType.App,
  id: '<your-app-id>',
  language: 'en-US',
})

console.log(meta.application?.name)
console.log(meta.design.theme.colorSchemes)
console.log(meta.i18n.translations)

exportUser Onboarding Flow (V2)

`executeEmbeddedUserOnboardingFlowV2` drives a post-sign-in onboarding sequence (e.g., profile completion, consent collection) without a browser redirect.

Parameters

config.urlrequired

string

Full endpoint URL. Mutually exclusive with `baseUrl`

config.baseUrlrequired

string

ThunderID base URL

config.payloadrequired

EmbeddedFlowExecuteRequestConfigV2

Flow request body

config.payload.applicationIdoptional

string

Application ID. Required for the first step

config.payload.flowTypeoptional

string

Must be `'USER_ONBOARDING'` for the first step

config.payload.executionIdoptional

string

Execution ID from a prior response

config.payload.inputsoptional

Record

Step input values

config.payload.challengeTokenoptional

string

Challenge token from a prior step

Example

import { executeEmbeddedUserOnboardingFlowV2, EmbeddedSignUpFlowStatusV2 } from '@thunderid/javascript'

// Step 1 — Initiate onboarding
const step1 = await executeEmbeddedUserOnboardingFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    applicationId: '<your-app-id>',
    flowType: 'USER_ONBOARDING',
  },
})

// Step 2 — Complete profile
const step2 = await executeEmbeddedUserOnboardingFlowV2({
  baseUrl: 'https://localhost:8090',
  payload: {
    executionId: step1.executionId,
    inputs: {
      'http://wso2.org/claims/mobile': '+1-555-0100',
    },
  },
})

functionBranding

The branding functions fetch the visual configuration (colors, logos, typography) defined in the ThunderID Console and apply it to your UI.

Example

import { getBrandingPreference } from '@thunderid/javascript'

const branding = await getBrandingPreference({
  baseUrl: 'https://localhost:8090',
  locale: 'en-US',
})

console.log(branding.preference?.theme?.LIGHT?.colors?.primary?.main)

functionConfiguration

The `initialize()` method accepts a configuration object (`AuthClientConfig`) that controls how the SDK connects to your ThunderID instance and manages authentication.

Example

import ThunderIDJavaScriptClient from '@thunderid/javascript'

const client = new ThunderIDJavaScriptClient()

await client.initialize({
  clientId: '<your-client-id>',
  baseUrl: 'https://localhost:8090',
})

functionErrors

The SDK uses a hierarchy of typed error classes. Catch specific classes to handle different failure modes distinctly.

Example

Error
└── ThunderIDError
    ├── ThunderIDAPIError
    └── ThunderIDRuntimeError
ThunderIDAuthException  (separate — thrown by auth flow internals)

functionHttpClient

`HttpClient` is an abstract base class that provides handler lifecycle management, request/response callbacks, and parallel request utilities. Platform SDKs extend it to add token attachment, retry logic, or custom transport implementations.

Example

import { HttpClient } from '@thunderid/javascript'
import type { HttpRequestConfig, HttpResponse } from '@thunderid/javascript'

class FetchHttpClient extends HttpClient {
  async transport<T>(config: HttpRequestConfig): Promise<HttpResponse<T>> {
    const response = await fetch(config.url, {
      method: config.method,
      headers: config.headers as HeadersInit,
      body: config.data ? JSON.stringify(config.data) : undefined,
    })

    return {
      data: await response.json(),
      status: response.status,
      statusText: response.statusText,
      headers: Object.fromEntries(response.headers.entries()),
    }
  }
}

functionInternationalization

The SDK ships with built-in translation bundles for ThunderID UI components and provides utilities for loading, extending, and normalizing translations.

Example

import { getDefaultI18nBundles } from '@thunderid/javascript'

const bundles = getDefaultI18nBundles()
console.log(bundles['en-US'])   // I18nBundle
console.log(bundles['fr-FR'])   // I18nBundle

functionStorageManager

`StorageManager` is the typed storage layer used internally by `ThunderIDJavaScriptClient`. It namespaces all stored data under a storage key derived from the client ID and instance ID. The storage layer provides typed methods for each data category: configuration, OIDC provider metadata, session data, and temporary (PKCE/state) data. Use it directly only when building platform adapters that need fine-grained control over stored auth state.

Example

import StorageManager from '@thunderid/javascript'

const storage = new StorageManager<Config>('instance_0-my-client-id', store)

functionTheme

The theme system provides a structured way to define colors, typography, spacing, and other visual properties used by ThunderID UI components. Use `createTheme()` to build a theme from scratch or apply partial overrides on top of the defaults.

Example

import { createTheme } from '@thunderid/javascript'

const theme = createTheme({
  colors: {
    primary: {
      main: '#6200ea',
      contrastText: '#ffffff',
    },
  },
})

// Apply CSS variables to the document root
Object.entries(theme.cssVariables).forEach(([key, value]) => {
  document.documentElement.style.setProperty(key, value)
})

functionThunderIDJavaScriptClient

`ThunderIDJavaScriptClient` is the base class that all platform-specific ThunderID clients extend. It provides OIDC discovery, PKCE, token exchange, session management, JWT decoding, and agent/OBO authentication. Instantiate it directly only when writing a custom platform adapter: for browser use, prefer `@thunderid/browser`; for React, use `@thunderid/react`.

Example

const client = new ThunderIDJavaScriptClient(storage?, cryptoUtils?)

functionUtilities

The SDK exports a set of utility functions used internally by platform SDKs and available to custom integrations.

Example

import { arrayBufferToBase64url } from '@thunderid/javascript'

const encoded = arrayBufferToBase64url(buffer)

exportUser Profile

These functions read and update user profile data from the OIDC userinfo endpoint.

Example

import { getUserInfo } from '@thunderid/javascript'

const user = await getUserInfo({
  url: 'https://localhost:8090/oauth2/userinfo',
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})

console.log(user.email, user.displayName)

exportUser Schemas

The SDK provides helpers for working with user schema data.

Example

import { flattenUserSchema } from '@thunderid/javascript'

const flat = flattenUserSchema(schemas, userProfile)