MonoCloud Authentication SDK
    Preparing search index...

    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.
    import { MonoCloudWebJSClient } from '@monocloud/auth-web-js';

    export const client = new MonoCloudWebJSClient({
      tenantDomain: 'https://your-tenant.us.monocloud.com',
      clientId: 'your-client-id',
      appUrl: 'http://localhost:3000',
      callbackPath: '/callback',
      signOutCallbackPath: '/logout',
    });
    Index

    Constructors

    constructor

    Properties

    oidcClient

    Methods

    getSession getTokens processSignInCallback processSignOutCallback refetchUserInfo refreshSession signIn signInSilent signOut

    Constructors

    • Initializes a new instance of MonoCloudWebJSClient.

      Parameters

      • options: MonoCloudWebJSClientOptions

        Configuration options for the client.

      • storage: IStorage = ...

        Storage implementation used to persist sessions. Defaults to LocalStorage.

      • OptionalpostCallbackFn: PostCallback

        Callback executed after a successful sign-in or sign-out callback. Useful for client-side router integration.

      • OptionalonSessionCreating: OnSessionCreating

        Hook invoked while creating or updating session.

      Returns MonoCloudWebJSClient

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

      export const client = new MonoCloudWebJSClient({
        tenantDomain: 'https://your-tenant.us.monocloud.com',
        clientId: 'your-client-id',
        appUrl: 'http://localhost:3000',
      });

      import { MonoCloudWebJSClient, MemoryStorage } from '@monocloud/auth-web-js';
      import { router } from './router';

      export const client = new MonoCloudWebJSClient(
        {
          tenantDomain: 'https://your-tenant.us.monocloud.com',
          clientId: 'your-client-id',
          appUrl: 'http://localhost:3000',
        },
        new MemoryStorage(),
        state => {
          // Use the router to navigate instead of a full page reload.
          router.push(state.returnUrl ?? '/dashboard');
        }
      );

    Properties

    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

    • 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

      • Optionaloptions: GetTokensOptions

        Options that control token retrieval (force refresh, scopes, resource).

      Returns Promise<MonoCloudTokens>

      The active tokens for the requested resource and scopes.

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

      const tokens = await client.getTokens({ forceRefresh: true });

      const tokens = await client.getTokens({
        resource: 'https://api.example.com',
        scopes: 'read:data',
      });

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

    • Processes the sign-in callback from the authorization server.

      Call this from the route handler that owns the sign-in callback path (callbackPath).

      Returns Promise<void>

      A promise that resolves when sign-in callback processing is complete.

      // /callback route handler
      await client.processSignInCallback();

      MonoCloudJsError If no sign-in callback state is found (for example, the page was reloaded after the callback was already consumed, or the route was hit without an in-progress sign-in flow).

    • Processes the sign-out callback from the authorization server.

      Call this from the route handler that owns the sign-out callback path (signOutCallbackPath).

      Returns Promise<void>

      A promise that resolves when sign-out callback processing is complete.

      // /logout route handler
      await client.processSignOutCallback();

      MonoCloudJsError If no sign-out callback state is found (for example, the page was reloaded after the callback was already consumed, or the route was hit without an in-progress sign-out flow).

    • 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>

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

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

    • 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 MonoCloudWebJSClient.signInSilent instead.

      Parameters

      • OptionalrefreshOptions: RefreshOptions

        Optional configuration for the refresh flow.

      Returns Promise<void>

      A promise that resolves when the session has been refreshed.

      await client.refreshSession();

      await client.refreshSession({
        refreshGrantOptions: {
          resource: 'https://api.example.com',
          scopes: 'read:data',
        },
      });

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

    • Initiates the sign-in flow.

      Parameters

      • OptionalsignInOptions: SignInOptions

        Optional configuration for the sign-in request.

      Returns Promise<void>

      document.getElementById('login-btn')!.addEventListener('click', async () => {
        // Standard top-level redirect to the authorization server.
        await client.signIn();
      });

      document.getElementById('login-popup-btn')!.addEventListener('click', async () => {
        // Opens a centered popup for authentication.
        await client.signIn({ mode: 'popup' });
        console.log('User finished popup flow!');
      });

      document.getElementById('register-btn')!.addEventListener('click', async () => {
        // Forces the identity provider to show the registration/sign-up screen.
        await client.signIn({ signUp: true });
      });

    • 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 - typically with error: 'login_required', 'interaction_required', 'consent_required', or 'account_selection_required', depending on why the authorization server cannot satisfy the request without user interaction.

      Parameters

      • OptionalsignInSilentOptions: SignInSilentOptions

        Optional configuration for the silent sign-in request.

      Returns Promise<MonoCloudSession>

      The newly established session.

      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;
        }
      }

      await client.signInSilent({
        resource: 'https://api.example.com',
        scopes: 'read:data',
      });

      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.

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

    • 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

      • OptionalsignOutOptions: 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).

      document.getElementById('logout-btn')!.addEventListener('click', async () => {
        await client.signOut();
      });

      document.getElementById('logout-popup-btn')!.addEventListener('click', async () => {
        // Opens a popup to perform federated sign-out while keeping the user on the current page.
        await client.signOut({ mode: 'popup' });
      });

    Settings

    On This Page

    Initialization
    Constructors
    Properties
    Methods