ThunderIDJavaScriptClient

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.

Constructor

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

Parameter	Type	Default	Description
storage	Storage	DefaultCacheStore	Custom storage implementation for session and config data
cryptoUtils	Crypto	DefaultCrypto	Custom cryptographic utilities (PKCE, JWT decoding)

Methods

Initialization

initialize(config, storage?)

Initialize the client with your application configuration. Must be called before using any other method.

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

Parameters:

Parameter	Type	Description
config	AuthClientConfig	Application configuration. See Configuration Reference
storage	Storage	Optional storage override for this instance

Returns: Promise<boolean> — true when initialization completes.

reInitialize(config)

Update configuration at runtime without creating a new instance. Forces OIDC discovery to re-run.

await client.reInitialize({ scopes: ['openid', 'profile', 'email'] })

Returns: Promise<boolean>

getConfiguration()

Retrieve the current configuration stored for this instance.

const config = client.getConfiguration()

Returns: T (the configuration type)

---

Authentication State

isSignedIn(userId?)

Check whether a user session is currently active (token exists and has not expired).

const signedIn = await client.isSignedIn()

Parameter	Type	Description
userId	string	Optional session ID for multi-user scenarios

Returns: Promise<boolean>

---

Token Management

getAccessToken(sessionId?)

Retrieve the raw access token string for the current session.

const token = await client.getAccessToken()

Parameter	Type	Description
sessionId	string	Optional session ID for multi-user scenarios

Returns: Promise<string>

decodeJwtToken<R>(token)

Decode a JWT token and return its payload as a typed object. Does not validate the signature.

const claims = await client.decodeJwtToken<{ sub: string; email: string }>(token)
console.log(claims.sub)

Returns: Promise<R>

exchangeToken(config, sessionId?)

Perform a token exchange request (RFC 8693 / custom grant). Sends a POST to the token endpoint with the provided data, optionally attaching the current access token.

const result = await client.exchangeToken({
  tokenEndpoint: 'https://localhost:8090/oauth2/token',
  data: {
    grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
    subject_token: '{{token}}',
    subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
  },
  attachToken: true,
  returnsSession: true,
})

Parameter	Type	Description
config	TokenExchangeRequestConfig	Token exchange configuration
config.tokenEndpoint	string	Token endpoint URL. Falls back to OIDC discovery
config.data	Record<string, string>	POST body fields. Use {{token}} to substitute the current access token
config.attachToken	boolean	Whether to include Authorization: Bearer <token>
config.returnsSession	boolean	When true, the response is stored as the new session
sessionId	string	Optional session ID

Returns: Promise<TokenResponse | Response | User>

getDiscoveryResponse()

Retrieve the cached OIDC discovery document, or null if the client has not been initialized.

const discovery = await client.getDiscoveryResponse()
console.log(discovery?.token_endpoint)

Returns: Promise<OIDCDiscoveryApiResponse | null>

---

User and Session

getUser(userId?)

Retrieve the authenticated user's identity claims, extracted from the stored ID token.

const user = await client.getUser()
console.log(user.displayName, user.email)

Parameter	Type	Description
userId	string	Optional session ID

Returns: Promise<User>

The User object includes:

Property	Type	Description
displayName	string	User's display name
username	string	Username
email	string	Email address
given_name	string	First name
family_name	string	Last name
picture	string	Profile picture URL
sub	string	Subject identifier

clearSession(sessionId?)

Clear stored session data for a given session ID.

client.clearSession()

Returns: void

setSession(sessionData, sessionId?)

Manually write session data into storage. Use when handling the token response externally.

await client.setSession({ access_token: '...', id_token: '...', expires_in: '3600' })

Returns: Promise<void>

getInstanceId()

Return the numeric instance ID assigned to this client. Used to namespace storage when running multiple SDK instances.

const id = client.getInstanceId() // 0 by default

Returns: number

---

Platform-specific Methods (to override)

Subclasses must implement these methods. Calling them on ThunderIDJavaScriptClient directly throws Error: Method not implemented.

Method	Signature	Description
signIn	(options?) => Promise<User | TokenResponse | undefined>	Initiate the authentication flow
signOut	(options?) => Promise<string | boolean>	End the session and sign out
signInSilently	(options?) => Promise<User | boolean | undefined>	Silent token refresh without user interaction
signUp	(options?) => Promise<void | EmbeddedFlowExecuteResponse>	Start a sign-up flow
recover	(payload) => Promise<EmbeddedFlowExecuteResponse>	Run a recovery flow
getUserProfile	(options?) => Promise<UserProfile>	Fetch the full user profile
updateUserProfile	(payload, userId?) => Promise<User>	Update the user's profile
isLoading	() => boolean	Whether an auth operation is in progress

---

Agent and OBO Authentication

getAgentToken(agentConfig)

Authenticate as a service agent using the embedded sign-in flow and return a token.

const token = await client.getAgentToken({
  agentID: 'my-agent@org.com',
  agentSecret: 'secret',
})

Returns: Promise<TokenResponse>

getOBOSignInURL(agentConfig)

Build an On-Behalf-Of (OBO) authorization URL that includes the agent's requested_actor parameter.

const url = await client.getOBOSignInURL({ agentID: 'my-agent@org.com', agentSecret: 'secret' })
window.location.href = url

Returns: Promise<string>

getOBOToken(agentConfig, authCodeResponse)

Exchange an authorization code plus an agent token for an OBO access token.

const token = await client.getOBOToken(agentConfig, {
  code: params.get('code')!,
  session_state: params.get('session_state') ?? '',
  state: params.get('state')!,
})

Returns: Promise<TokenResponse>

---

Static Helpers

ThunderIDJavaScriptClient.isSignOutSuccessful(url)

Check whether a post-logout redirect URL indicates a successful sign-out.

if (ThunderIDJavaScriptClient.isSignOutSuccessful(window.location.href)) {
  console.log('Signed out successfully')
}

Returns: boolean

ThunderIDJavaScriptClient.didSignOutFail(url)

Check whether a post-logout redirect URL indicates a failed sign-out (same state parameter but with an error query param).

if (ThunderIDJavaScriptClient.didSignOutFail(window.location.href)) {
  console.error('Sign-out failed')
}

Returns: boolean

---

Protected Methods (for subclass use)

These methods are available to subclasses building platform adapters:

Method	Description
loadOpenIDProviderConfiguration(forceInit?)	Fetch and cache the OIDC discovery document
getSignInUrl(requestConfig?, userId?)	Build the OAuth 2.0 authorization URL with PKCE
requestAccessToken(code, sessionState, state, userId?, tokenRequestConfig?)	Exchange an authorization code for tokens
getSignOutUrl(userId?)	Build the OIDC end-session URL
refreshAccessToken(userId?)	Use the refresh token to get a new access token
revokeAccessToken(userId?)	Revoke the current access token
getDecodedIdToken(userId?, idToken?)	Decode the stored ID token
getIdToken(userId?)	Get the raw ID token string
getUserSession(userId?)	Get scopes and session state for the current session
getOpenIDProviderEndpoints()	Get the cached OIDC endpoint URLs
getStorageManager()	Access the underlying StorageManager instance
getCryptoHelper()	Access the underlying IsomorphicCrypto instance