Class: MonoCloudWebJSClient

MonoCloudWebJSClient is the core SDK entry point for integrating MonoCloud authentication into single-page applications (SPAs) and other browser-based JavaScript environments.

Features:

Redirect and popup sign-in / sign-out flows.
Silent sign-in via a hidden iframe (prompt=none) for restoring SSO sessions at app bootstrap.
Refresh Token Grant based session refreshing.
Session and token storage with pluggable storage adapters.
Automatic PKCE, state, and nonce generation and validation.

Initialization

src/auth.ts

import { MonoCloudWebJSClient } from '@monocloud/auth-web-js';

export const client = new MonoCloudWebJSClient({
  tenantDomain: 'https://<your-tenant>',
  clientId: '<your-client-id>',
});

Constructors

Constructor

new MonoCloudWebJSClient(options: MonoCloudWebJSClientOptions): MonoCloudWebJSClient

Initializes a new instance of MonoCloudWebJSClient.

Parameters

Parameter	Type	Description
`options`	`MonoCloudWebJSClientOptions`	Configuration options for the client.

Returns

MonoCloudWebJSClient

Examples

src/auth.ts

import { MonoCloudWebJSClient } from '@monocloud/auth-web-js';

export const client = new MonoCloudWebJSClient({
  tenantDomain: 'https://<your-tenant>',
  clientId: '<your-client-id>',
});

Properties

Property	Type	Description
`oidcClient`	`MonoCloudOidcClient`	Underlying OpenID Connect client used for advanced authorization and token operations. Use this when you need lower-level access to OIDC protocol operations not directly exposed by the SDK.

Methods

getSession()

getSession(): Promise<MonoCloudSession | undefined>

Retrieves the current session object from the configured storage.

Returns

Promise<MonoCloudSession | undefined>

The active session, or undefined if not authenticated.

Example

src/app.ts

const session = await client.getSession();
if (session) {
  console.log('User is logged in:', session.user);
}

getTokens()

getTokens(options?: GetTokensOptions): Promise<MonoCloudTokens>

Retrieves the active tokens for the current session.

If the access token is expired (or about to expire), this method automatically attempts to refresh it using the Refresh Token Grant before returning.

Parameters

Parameter	Type	Description
`options?`	`GetTokensOptions`	Options that control token retrieval (force refresh, scopes, resource).

Returns

Promise<MonoCloudTokens>

The active tokens for the requested resource and scopes.

Examples

src/app.ts

const tokens = await client.getTokens();
console.log(tokens.accessToken);

Throws

MonoCloudValidationError If no session exists or the access token cannot be located.

processCallback()

processCallback(): Promise<void>

Processes the authentication callback from the authorization server.

Call this once on application startup (typically in your entry point or router). It inspects the current URL together with the persisted callback state and automatically completes a pending sign-in or sign-out flow - there is no need to dispatch on the route yourself.

Returns

Promise<void>

A promise that resolves when callback processing is complete.

Example

src/main.ts

async function init() {
  // Complete any pending redirect callback before rendering.
  await client.processCallback();

  // Continue mounting the app.
}

init();

refetchUserInfo()

refetchUserInfo(): Promise<void>

Refetches user information from the UserInfo endpoint and updates the local session.

The default access token (matching the client's configured default resource and authorized scopes) is used to call the UserInfo endpoint.

Returns

Promise<void>

Example

src/app.ts

await client.refetchUserInfo();
const session = await client.getSession();
console.log('Updated user data:', session?.user);

Throws

MonoCloudValidationError If the session is invalid or the default access token is missing.

refreshSession()

refreshSession(refreshOptions?: RefreshOptions): Promise<void>

Refreshes the current user's session using the OAuth 2.0 Refresh Token Grant.

Requires a session that includes a refresh token (obtained by including the offline_access scope at sign-in).

To start a fresh, non-interactive authorization (for example, on app bootstrap when there is no local session yet) use signInSilent() instead.

Parameters

Parameter	Type	Description
`refreshOptions?`	`RefreshOptions`	Optional configuration for the refresh flow.

Returns

Promise<void>

A promise that resolves when the session has been refreshed.

Examples

src/app.ts

await client.refreshSession();

Throws

MonoCloudValidationError If the session is invalid or missing a refresh token.

signIn(signInOptions?: SignInOptions): Promise<void>

Initiates the sign-in flow.

Parameters

Parameter	Type	Description
`signInOptions?`	`SignInOptions`	Optional configuration for the sign-in request.

Returns

Promise<void>

Examples

src/app.ts

await client.signIn();

signInSilent()

signInSilent(signInSilentOptions?: SignInSilentOptions): Promise<MonoCloudSession>

Attempts to silently sign the user in using a hidden iframe and prompt=none.

Useful for restoring a session at app bootstrap when the user is signed in at MonoCloud but no local session exists yet (for example, after opening a new tab or a hard refresh that cleared in-memory storage).

The method runs a full authorization round-trip through a hidden iframe. If MonoCloud has a valid session it resolves to the new session. Otherwise it rejects with a MonoCloudOPError.

Parameters

Parameter	Type	Description
`signInSilentOptions?`	`SignInSilentOptions`	Optional configuration for the silent sign-in request.

Returns

Promise<MonoCloudSession>

The newly established session.

Example

src/app.ts

import { MonoCloudOPError } from '@monocloud/auth-web-js';

try {
  const session = await client.signInSilent();
  console.log('Restored session for:', session.user);
} catch (error) {
  if (error instanceof MonoCloudOPError && error.error === 'login_required') {
    console.log('Not signed in');
  } else {
    throw error;
  }
}

Throws

MonoCloudOPError If the authorization server cannot satisfy the request - for example, because the user has no IdP session (login_required) or interaction is otherwise required.

Throws

MonoCloudJsError If the iframe cannot be created (for example, in a cross-origin-isolated context) or the authentication window times out.

signOut()

signOut(signOutOptions?: SignOutOptions): Promise<void>

Initiates the sign-out flow.

Clears the local session and, when federatedSignOut is enabled, also signs the user out of MonoCloud (Single Sign-Out).

Parameters

Parameter	Type	Description
`signOutOptions?`	`SignOutOptions`	Optional configuration for the sign-out request.

Returns

Promise<void>

A promise that resolves when the sign-out flow has been initiated (redirect mode) or completed (popup mode).

Examples

src/app.ts

await client.signOut();