React – 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

Let the provider complete callbacks automatically with autoProcessCallback
Handle the callback on a dedicated route 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 React quickstart or the installation guide.

You should already have:

A Single Page App configured in MonoCloud
The @monocloud/auth-react SDK installed
Your app wrapped with <MonoCloudAuthProvider>

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 your application with parameters in the URL.

The SDK must process that callback to:

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

Process callbacks automatically (default)

By default, <MonoCloudAuthProvider> processes the callback automatically when it mounts. No extra wiring is needed - the authentication state becomes available through useAuth() once the callback completes.

src/main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { MonoCloudAuthProvider } from "@monocloud/auth-react";
import App from "./App.tsx";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <MonoCloudAuthProvider
      tenantDomain="https://<your-domain>"
      clientId="<your-client-id>"
    >
      <App />
    </MonoCloudAuthProvider>
  </StrictMode>
);

With this setup, register your application's origin (for example, http://localhost:5173) as the Callback URL in the Dashboard.

Handle the callback on a dedicated route

If you prefer a dedicated callback route (for example, /callback), disable automatic processing on the provider and render <ProcessCallback /> on that route.

<ProcessCallback /> completes the pending callback and synchronizes the authentication state. It renders no UI of its own beyond the optional loading, error, and children slots.

src/main.tsx

<MonoCloudAuthProvider
  tenantDomain="https://<your-domain>"
  clientId="<your-client-id>"
  autoProcessCallback={false}
  callbackPath="/callback"
>
  <App />
</MonoCloudAuthProvider>

src/Callback.tsx

import { ProcessCallback } from "@monocloud/auth-react";

export default function Callback() {
  return (
    <ProcessCallback
      loading={<p>Completing sign in...</p>}
      error={(err) => <p>Sign in failed: {err.message}</p>}
    />
  );
}

Render <Callback /> on the route MonoCloud redirects back to, and register that route (for example, http://localhost:5173/callback) as the Callback URL in the Dashboard.

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

tsx

const { signIn } = useAuth();

await signIn({ returnUrl: "/dashboard" });

By default, the SDK performs a full page reload to the returnUrl once the callback completes. To navigate with a client-side router instead of reloading, use postCallback.

Integrate with a client-side router

A full-page navigation resets any in-memory state. If your app uses a client-side router and you want to keep that state, set the postCallback option on the provider to navigate with the router instead. postCallback runs for both sign-in and sign-out callbacks, after the SDK has persisted the session.

src/main.tsx

import { MonoCloudAuthProvider } from "@monocloud/auth-react";
import { useNavigate } from "react-router";

export default function Root() {
  const navigate = useNavigate();

  return (
    <MonoCloudAuthProvider
      tenantDomain="https://<your-domain>"
      clientId="<your-client-id>"
      autoProcessCallback={false}
      postCallback={(state) => navigate(state.returnUrl ?? "/")}
    >
      <App />
    </MonoCloudAuthProvider>
  );
}

How it works:

postCallback runs after the SDK has persisted the session
state.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

A failed callback sets error on the authentication state, so const { error } = useAuth() reflects it in both modes - automatic processing and a dedicated <ProcessCallback /> route. The <ProcessCallback /> error slot is simply a convenient way to render that same error inline on the callback route.

With automatic processing

Read error from useAuth() anywhere in your app:

src/App.tsx

import { useAuth } from "@monocloud/auth-react";

export default function App() {
  const { isLoading, error } = useAuth();

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Authentication failed: {error.message}</p>;
  }

  return <p>Signed in</p>;
}

With a dedicated callback route

Render the error through the <ProcessCallback /> error slot. It accepts a node or a function that receives the error:

src/Callback.tsx

import { ProcessCallback } from "@monocloud/auth-react";

export default function Callback() {
  return (
    <ProcessCallback
      loading={<p>Completing sign in...</p>}
      error={(err) => <p>Authentication failed: {err.message}</p>}
    />
  );
}

Handle Sign-in and Sign-out Callbacks

What you'll cover

Before you begin

How callbacks work

Process callbacks automatically (default)

Handle the callback on a dedicated route

Return the user after sign-in

Integrate with a client-side router

Handle errors during the callback

With automatic processing

With a dedicated callback route

Next steps