JavaScript SDK

The ThunderID JavaScript SDK (@thunderid/javascript) is the framework-agnostic core library that powers platform-specific SDKs such as @thunderid/browser, @thunderid/react, and @thunderid/express. Use it directly when building custom integrations, writing platform adapters, or working in environments without a dedicated ThunderID SDK.

Installation

Install the ThunderID JavaScript SDK using your preferred package manager:

npm

npm install @thunderid/javascript

Yarn

yarn add @thunderid/javascript

pnpm

pnpm add @thunderid/javascript

Bun

bun add @thunderid/javascript

When to use this SDK

Use case	Recommended SDK
React applications	@thunderid/react
Vanilla JavaScript browser apps	@thunderid/browser
Express.js middleware	@thunderid/express
Custom platform adapter	@thunderid/javascript (this SDK)
Building a new framework SDK	@thunderid/javascript (this SDK)

Quick Example

Extend ThunderIDJavaScriptClient to build a platform-specific client:

src/my-client.ts

import ThunderIDJavaScriptClient from '@thunderid/javascript'

class MyCustomClient extends ThunderIDJavaScriptClient {
  async signIn(options = {}) {
    await this.loadOpenIDProviderConfiguration()
    const url = await this.getSignInUrl(options)
    window.location.href = url
  }

  async handleCallback() {
    const params = new URLSearchParams(window.location.search)
    return this.requestAccessToken(
      params.get('code')!,
      params.get('session_state') ?? '',
      params.get('state')!,
    )
  }
}

const auth = new MyCustomClient()

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

Features

Core APIs

• ThunderIDJavaScriptClient — Base class for all platform SDKs. Handles OIDC discovery, PKCE, token exchange, session storage, JWT decoding, and agent/OBO authentication.
• Configuration — Full reference for all initialization options including auth, token validation, discovery, and preferences.
• HttpClient — Abstract HTTP client base with handler lifecycle, request/response callbacks, and parallel request support.
• StorageManager — Typed storage layer for config, OIDC metadata, session, and temporary PKCE data.

Auth Flow Functions

Standalone functions for driving authentication flows step-by-step without browser redirects.

V2 Flows (recommended)

• Sign-In Flow — executeEmbeddedSignInFlowV2
• Sign-Up Flow — executeEmbeddedSignUpFlowV2
• Recovery Flow — executeEmbeddedRecoveryFlowV2
• User Onboarding Flow — executeEmbeddedUserOnboardingFlowV2
• Flow Meta — getFlowMetaV2 — aggregated app/org branding, theme, and i18n metadata

V1 Flows

• Embedded Sign-In Flow — initializeEmbeddedSignInFlow / executeEmbeddedSignInFlow
• Embedded Sign-Up Flow — executeEmbeddedSignUpFlow

User & Profile

• User Profile — getUserInfo, getScim2Me, updateMeProfile
• SCIM2 Schemas — getSchemas and schema utility functions (flattenUserSchema, generateUserProfile, resolveFieldType)

Organizations

• Organizations — getAllOrganizations, getMeOrganizations, getOrganization, createOrganization, updateOrganization, createPatchOperations
• Organization Units — getOrganizationUnitChildren

Branding & Theme

• Branding — getBrandingPreference, transformBrandingPreferenceToTheme
• Theme — createTheme, DEFAULT_THEME

Internationalization

• Internationalization — getDefaultI18nBundles, normalizeTranslations, TranslationBundleConstants. Built-in support for 9 locales.

Errors

• Errors — ThunderIDError, ThunderIDAPIError, ThunderIDRuntimeError, ThunderIDAuthException

Utilities

• Utilities — Encoding, auth helpers, URL utilities, data manipulation, V2 flow template literals, BEM styling, and structured logging.