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 App Router.

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

What you'll cover in this guide

✅ Set up the MonoCloud authentication handler
✅ Add the MonoCloud Auth Provider
✅ Explore further steps

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 three folders in the src/app/ directory.

Inside your project's src/app/ directory, create a new folder named api.
In that new folder, create a folder named auth.
Inside there, create a new folder named [...monocloud].

The last of these folders is a catch-all route that will handle all the authentication requests from MonoCloud.

Inside the new [...monocloud] directory, create a route.ts file and add the code below:

src/app/api/auth/[...monocloud]/route.ts

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

export const GET = 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:

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

Wrap the <body> of your application with the component by modifying the layout.tsx file in the src/app folder as follows:

src/app/layout.tsx

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import { MonoCloudAuthProvider } from "@monocloud/nextjs-auth/client";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <MonoCloudAuthProvider>
        <body className={inter.className}>
          {children}
        </body>
      </MonoCloudAuthProvider>
    </html>
  );
}

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:

Quickstarts

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