JavaScript – Handle Sign-in and Sign-out Callbacks

This guide shows how to process the sign-in and sign-out callbacks that MonoCloud redirects to after authentication, and how to integrate with a client-side router so the browser does not perform a full page reload.

What you'll cover

Complete sign-in and sign-out flows with processCallback()
Return the user to the page they were on before signing in
Hook into a client-side router with postCallback

Before you begin

This guide assumes you've completed the JavaScript quickstart or the installation guide.

You should already have:

A Single Page App configured in MonoCloud
The @monocloud/auth-web-js SDK installed
A MonoCloudWebJSClient

How callbacks work

When you call signIn() or signOut() in redirect mode, the SDK navigates the browser to MonoCloud's authorize or end-session endpoint. After the user completes the flow, MonoCloud redirects back to the callbackPath or signOutPath with parameters in the URL.

Your application must call processCallback() on startup so the SDK can:

Exchange the authorization code for tokens (sign-in)
Validate the ID token and persist the session
Clear the callback parameters from the URL
Navigate the user to the original page

If processCallback() is not called, the session is never created and the user sees a URL full of OAuth parameters.

Process the callback on startup

Call processCallback() once when your app loads. It inspects the current URL and the persisted callback state to automatically complete whichever flow is pending — there's no need to dispatch on the route yourself.

src/main.ts

await client.processCallback();

Run processCallback() before your UI renders. The session is not available until the callback has completed.

Pass a returnUrl to signIn() to control where the user lands after authentication completes.

src/main.ts

client.signIn({ returnUrl: "/dashboard" });

By default, the SDK performs a full page reload to the returnUrl once the callback completes. If no returnUrl is provided, it only strips the OAuth query parameters from the URL and the browser stays on the callback path. To navigate with a client-side router instead of reloading, see postCallback.

Integrate with a client-side router

The default behavior described above uses a full-page navigation, which resets any in-memory state. If your app uses a client-side router and you want to keep that state, replace it with a router navigation by setting the postCallback option when constructing the client. postCallback runs for both sign-in and sign-out callbacks.

src/auth.ts

import { MonoCloudWebJSClient } from "@monocloud/auth-web-js";
import { router } from "./router";

export const client = new MonoCloudWebJSClient({
  tenantDomain: "https://<your-domain>",
  clientId: "<your-client-id>",
  postCallback: async ({ returnUrl }) => {
    if (returnUrl) {
      router.navigate(returnUrl);
    }
  },
});

How it works:

postCallback runs after the SDK has persisted the session
returnUrl is the value passed to signIn({ returnUrl }) or signOut({ returnUrl })
Navigating with your router avoids the full page reload

Handle errors during the callback

processCallback() throws when the authorization server returns an error or the token exchange fails. Catch it to render a friendly error message:

src/main.ts

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

try {
  await client.processCallback();
} catch (error) {
  if (error instanceof MonoCloudOPError) {
    console.error(`Authentication failed: ${error.error} - ${error.errorDescription}`);
  } else {
    throw error;
  }
}

Handle Sign-in and Sign-out Callbacks

What you'll cover

Before you begin

How callbacks work

Process the callback on startup

Return the user after sign-in

Integrate with a client-side router

Handle errors during the callback

Next steps