Adding the Auth Handler

The MonoCloud Next.js SDK provides the functionality to authenticate users, protect routes, and manage user sessions in your Next.js application.

In this guide, you'll work through the initial steps to add authentication to your Next.js application using the Page Router.

Using Next.js with the App Router? Visit the App Router documentation.

Installing and configuring the SDK

If you haven't already, you need to register with MonoCloud, install the SDK, and then connect the SDK to your MonoCloud account.

Read the installation and configuration guide.

Adding the authentication handler

The first step to integrating MonoCloud with your Next.js application is to set up an authentication handler that will manage user authentication with MonoCloud on the server side.

We'll start by creating the folders we need and a catch-all route that will handle all the authentication requests from MonoCloud.

  1. In src/pages/api, create a new folder named auth.
  2. Inside there, set-up the catch-all route by creating a file named [...monocloud].ts.

In the new file, paste the following code:

import { monoCloudAuth } from "@monocloud/nextjs-auth";

export default monoCloudAuth();

This sets up the monoCloudAuth() function to handle the following types of requests:

  • signin: Manages sign-in requests made from the browser.
  • signout: Manages sign-out requests made from the browser.
  • userinfo: Retrieves the currently signed-in user's profile.
  • callback: Processes callbacks from MonoCloud following authentication and sets up the user session.

Adding the authentication provider

The MonoCloud SDK includes a MonoCloudAuthProvider component, which can be used to wrap your application and provide a user session object to all nested components. This client-side component takes care of:

  1. Keeping the session updated and synchronized between different tabs and windows.
  2. Sharing the session object across components using React Context, but only for client-rendered components.

Wrap your application with the component by modifying the _app.tsx file in the src/pages folder as follows:

import "@/styles/globals.css";
import type { AppProps } from "next/app";
import { MonoCloudAuthProvider } from "@monocloud/nextjs-auth/client";

export default function App({
  pageProps: { session, ...pageProps }
}: AppProps) {
  return (
      <Component {...pageProps} />

You can now use the useUser() hook throughout your application to access the user's profile.

Next: Protecting application routes

Now that you've set up MonoCloud to handle authentication in your Next.js app, the next step is to protect your application's routes and pages. Depending on the types of routes you need to protect, the SDK provides several ways to achieve this:


Want to get a demo app up and running quickly? Check out our Next.js quickstarts: