Class MonoCloudNextClient

constructor

• new MonoCloudNextClient(options?: MonoCloudOptions): MonoCloudNextClient

  Parameters

  • Optionaloptions: MonoCloudOptions

    Configuration options including domain, client ID, and secret.

  Returns MonoCloudNextClient

ReadonlycoreClient

// req and res must implement IMonoCloudCookieRequest/Response
await monoCloud.coreClient.destroySession(request, response);
Copy

oidcClient

• get oidcClient(): MonoCloudOidcClient

  The underlying OIDC client instance used for low-level OpenID Connect operations.

  Returns MonoCloudOidcClient

  Example

  // Manually revoke an access token
  await client.oidcClient.revokeToken(accessToken, 'access_token');
  Copy

authMiddleware

• authMiddleware(options?: MonoCloudMiddlewareOptions): NextMiddleware

  A middleware/proxy that protects pages and APIs and handles authentication.

  Parameters

  • Optionaloptions: MonoCloudMiddlewareOptions

    Middleware configuration options

  Returns NextMiddleware

  A Next.js middleware/proxy function.

  Example: Protect All Routes

  • Default behavior: protect all routes matched by config.matcher

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.authMiddleware();
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Protect Selected Routes

  • Protect only the routes listed in protectedRoutes

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.authMiddleware({
    protectedRoutes: ["/api/admin", "^/api/protected(/.*)?$"],
  });
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Make All Routes Public

  • Do not protect any routes; MonoCloud still handles auth endpoints

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.authMiddleware({
    protectedRoutes: [],
  });
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Protect Routes Dynamically

  • Decide at runtime which routes to protect

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.authMiddleware({
    protectedRoutes: (req) => {
      return req.nextUrl.pathname.startsWith("/api/protected");
    },
  });
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Protect routes based on groups

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.authMiddleware({
    // group names or IDs
    protectedRoutes: [
      {
        groups: ["admin", "editor", "537e7c3d-a442-4b5b-b308-30837aa045a4"],
        routes: ["/internal", "/api/internal(.*)"],
      },
    ],
  });
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

• authMiddleware(
      request: NextRequest,
      event: NextFetchEvent,
  ): NextMiddlewareResult | Promise<NextMiddlewareResult>

  A middleware that protects pages and APIs and handles authentication.

  Parameters

  • request: NextRequest

    The Next.js fetch event object.

  • event: NextFetchEvent

    The associated fetch event Docs.

  Returns NextMiddlewareResult | Promise<NextMiddlewareResult>

  A promise resolving to a Next.js middleware result or a Next.js middleware result.

  Example: Nest Custom Middleware

  • Use your own middleware wrapper and call MonoCloud only for specific routes

  import { monoCloud } from "@/lib/monocloud";
  import { NextFetchEvent, NextRequest, NextResponse } from "next/server";
  
  export default function customMiddleware(req: NextRequest, evt: NextFetchEvent) {
    if (req.nextUrl.pathname.startsWith("/api/protected")) {
      return monoCloud.authMiddleware(req, evt);
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

getSession

• getSession(): Promise<MonoCloudSession | undefined>

  SSR Components, Actions, Middleware or API Handlers

  Retrieves the session object for the currently authenticated user on the server.

  Use Case:

  • App Router Server Components (RSC).
  • Server Actions
  • Route Handlers (App Router only).
  • Middleware (App Router and Pages Router).

  Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.

  Returns Promise<MonoCloudSession | undefined>

  MonoCloudSession if found, or undefined.

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextResponse } from "next/server";
  
  export default async function middleware() {
    const session = await monoCloud.getSession();
  
    if (!session) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const session = await monoCloud.getSession();
  
    return NextResponse.json({ name: session?.user.name });
  };
  Copy

  Example: React Server Components

  import { monoCloud } from "@/lib/monocloud";
  
  export default async function Home() {
    const session = await monoCloud.getSession();
  
    return <div>{session?.user.name}</div>;
  }
  Copy

  Example: Server Action

  "use server";
  
  import { monoCloud } from "@/lib/monocloud";
  
  export async function getUserAction() {
    const session = await monoCloud.getSession();
  
    return { name: session?.user.name };
  }
  Copy

• getSession(
      req: Request | NextRequest,
      res?: Response | NextResponse<unknown>,
  ): Promise<MonoCloudSession | undefined>

  Middleware/Proxy or Route Handlers

  Retrieves the session object for the currently authenticated user on the server.

  Use Case:

  • Middleware (for both App and Pages Router).
  • App Router Route Handlers (API routes).
  • Edge functions.

  Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.

  Parameters

  • req: Request | NextRequest

    NextRequest

  • Optionalres: Response | NextResponse<unknown>

    An optional NextResponse instance. Pass this if you have already initialized a response; otherwise, omit this parameter.

  Returns Promise<MonoCloudSession | undefined>

  MonoCloudSession if found, or undefined.

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const session = await monoCloud.getSession(req);
  
    if (!session) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Middleware/Proxy (Custom Response)

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const res = NextResponse.next();
  
    const session = await monoCloud.getSession(req, res);
  
    if (!session) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    res.headers.set("x-auth-status", "active");
  
    return res;
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: API Handler

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const session = await monoCloud.getSession(req);
  
    return NextResponse.json({ name: session?.user.name });
  };
  Copy

  Example: API Handler with NextResponse

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("YOUR CUSTOM RESPONSE");
  
    const session = await monoCloud.getSession(req, res);
  
    if (session?.user) {
      res.cookies.set("something", "important");
    }
  
    return res;
  };
  Copy

• getSession(
      req: NextApiRequest | IncomingMessage,
      res: NextApiResponse | ServerResponse<IncomingMessage>,
  ): Promise<MonoCloudSession | undefined>

  Pages Router (Node.js Runtime)

  Retrieves the session object for the currently authenticated user on the server.

  Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.

  Parameters

  • req: NextApiRequest | IncomingMessage

    NextApiRequest

  • res: NextApiResponse | ServerResponse<IncomingMessage>

    NextApiResponse

  Returns Promise<MonoCloudSession | undefined>

  MonoCloudSession if found, or undefined.

  Example: API Handler

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  type Data = {
    name?: string;
  };
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse<Data>
  ) {
    const session = await monoCloud.getSession(req, res);
  
    res.status(200).json({ name: session?.user.name });
  }
  Copy

  Example: SSR Component

  import { monoCloud } from "@/lib/monocloud";
  import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
  
  type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
  
  export default function Home({ session }: HomeProps) {
    return <pre>Session: {JSON.stringify(session, null, 2)}</pre>;
  }
  
  export const getServerSideProps: GetServerSideProps = async (context) => {
    const session = await monoCloud.getSession(context.req, context.res);
  
    return {
      props: {
        session: session ?? null,
      },
    };
  };
  Copy

getTokens

• getTokens(options?: GetTokensOptions): Promise<MonoCloudTokens>

  SSR Components, Actions, Middleware or API Handlers

  Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.

  Use Case:

  • App Router Server Components (RSC).
  • Server Actions
  • Route Handlers (App Router only).
  • Middleware (App Router and Pages Router).

  Parameters

  • Optionaloptions: GetTokensOptions

    Configuration options for token retrieval.

  Returns Promise<MonoCloudTokens>

  Throws

  MonoCloudValidationError If session is not found

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextResponse } from "next/server";
  
  export default async function middleware() {
    const tokens = await monoCloud.getTokens();
  
    if (tokens.isExpired) {
      return new NextResponse("Tokens expired", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const tokens = await monoCloud.getTokens();
  
    return NextResponse.json({ expired: tokens.isExpired });
  };
  Copy

  Example: React Server Components

  import { monoCloud } from "@/lib/monocloud";
  
  export default async function Home() {
    const tokens = await monoCloud.getTokens();
  
    return <div>Expired: {tokens.isExpired.toString()}</div>;
  }
  Copy

  Example: Server Action

  "use server";
  
  import { monoCloud } from "@/lib/monocloud";
  
  export async function getExpiredAction() {
    const tokens = await monoCloud.getTokens();
  
    return { expired: tokens.isExpired };
  }
  Copy

  Example: Refresh Default Token

  The default token is an access token with scopes set through MONOCLOUD_AUTH_SCOPES or options.defaultAuthParams.scopes, and resources set through MONOCLOUD_AUTH_RESOURCE or options.defaultAuthParams.resource. This token is refreshed when calling getTokens without parameters.

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
  // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
  const tokens = await monoCloud.getTokens({ forceRefresh: true });
  
  return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

  Example: Request new access token for resource(s)

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  The following example shows how to request a new token scoped to two non-exclusive resources.

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const tokens = await monoCloud.getTokens({
      resource: "https://first.example.com https://second.example.com",
      scopes: "read:first read:second shared",
    });
  
    return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

  Example: Request an exclusive token

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const tokens = await monoCloud.getTokens({
      resource: "https://exclusive.example.com",
      scopes: "read:exclusive shared",
    });
  
    return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

• getTokens(
      req: Request | NextRequest,
      options?: GetTokensOptions,
  ): Promise<MonoCloudTokens>

  Middleware/Proxy or Route Handlers

  Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.

  Use Case:

  • Middleware (for both App and Pages Router).
  • App Router Route Handlers (API routes).
  • Edge functions.

  Parameters

  • req: Request | NextRequest

    NextRequest

  • Optionaloptions: GetTokensOptions

    Configuration options for token retrieval.

  Returns Promise<MonoCloudTokens>

  Throws

  MonoCloudValidationError If session is not found

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const tokens = await monoCloud.getTokens(req);
  
    if (tokens.isExpired) {
      return new NextResponse("Tokens expired", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const tokens = await monoCloud.getTokens(req);
  
    return NextResponse.json({ expired: tokens?.isExpired });
  };
  Copy

  Example: Refresh Default Token

  The default token is an access token with scopes set through MONOCLOUD_AUTH_SCOPES or options.defaultAuthParams.scopes, and resources set through MONOCLOUD_AUTH_RESOURCE or options.defaultAuthParams.resource. This token is refreshed when calling getTokens without parameters.

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
    const tokens = await monoCloud.getTokens(req, { forceRefresh: true });
  
    return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

  Example: Request new access token for resource(s)

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  The following example shows how to request a new token scoped to two non-exclusive resources.

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const tokens = await monoCloud.getTokens(req, {
      resource: "https://first.example.com https://second.example.com",
      scopes: "read:first read:second shared",
    });
  
    return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

  Example: Request an exclusive token

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const tokens = await monoCloud.getTokens(req, {
      resource: "https://exclusive.example.com",
      scopes: "read:exclusive shared",
    });
  
    return NextResponse.json({ accessToken: tokens?.accessToken });
  };
  Copy

• getTokens(
      req: Request | NextRequest,
      res: Response | NextResponse<unknown>,
      options?: GetTokensOptions,
  ): Promise<MonoCloudTokens>

  Middleware/Proxy or Route Handlers (Custom Response)

  Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens and updates the provided response object.

  Use Case:

  • Middleware (when modifying the response).
  • App Router Route Handlers (when a NextResponse is already initialized).

  Parameters

  • req: Request | NextRequest

    NextRequest

  • res: Response | NextResponse<unknown>

    An optional NextResponse instance. Pass this if you have already initialized a response and want token updates (e.g., refreshing) to be applied to it.

  • Optionaloptions: GetTokensOptions

    Configuration options for token retrieval.

  Returns Promise<MonoCloudTokens>

  Throws

  MonoCloudValidationError If session is not found

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const res = NextResponse.next();
  
    const tokens = await monoCloud.getTokens(req, res);
  
    res.headers.set("x-tokens-expired", tokens.isExpired.toString());
  
    return res;
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: API Handler with NextResponse

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("Custom Body");
  
    const tokens = await monoCloud.getTokens(req, res);
  
    if (!tokens.isExpired) {
      res.headers.set("x-auth-status", "active");
    }
  
    return res;
  };
  Copy

  Example: Refresh Default Token

  The default token is an access token with scopes set through MONOCLOUD_AUTH_SCOPES or options.defaultAuthParams.scopes, and resources set through MONOCLOUD_AUTH_RESOURCE or options.defaultAuthParams.resource. This token is refreshed when calling getTokens without parameters.

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("Custom Body");
  
    // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
    const tokens = await monoCloud.getTokens(req, res, { forceRefresh: true });
  
    if (!tokens.isExpired) {
      res.headers.set("x-auth-status", "active");
    }
  
    return res;
  };
  Copy

  Example: Request new access token for resource(s)

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  The following example shows how to request a new token scoped to two non-exclusive resources.

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("Custom Body");
  
    const tokens = await monoCloud.getTokens(req, res, {
      resource: "https://first.example.com https://second.example.com",
      scopes: "read:first read:second shared",
    });
  
    if (!tokens.isExpired) {
      res.headers.set("x-auth-status", "active");
    }
  
    return res;
  };
  Copy

  Example: Request an exclusive token

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("Custom Body");
  
    const tokens = await monoCloud.getTokens(req, res, {
      resource: "https://exclusive.example.com",
      scopes: "read:exclusive shared",
    });
  
    if (!tokens.isExpired) {
      res.headers.set("x-auth-status", "active");
    }
  
    return res;
  };
  Copy

• getTokens(
      req: NextApiRequest | IncomingMessage,
      res: NextApiResponse | ServerResponse<IncomingMessage>,
      options?: GetTokensOptions,
  ): Promise<MonoCloudTokens>

  Pages Router (Node.js Runtime)

  Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.

  Parameters

  • req: NextApiRequest | IncomingMessage

    The NextApiRequest or IncomingMessage.

  • res: NextApiResponse | ServerResponse<IncomingMessage>

    The NextApiResponse or ServerResponse.

  • Optionaloptions: GetTokensOptions

    Configuration options for token retrieval.

  Returns Promise<MonoCloudTokens>

  Throws

  MonoCloudValidationError If session is not found

  Example: API Route

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    const tokens = await monoCloud.getTokens(req, res);
  
    res.status(200).json({ accessToken: tokens?.accessToken });
  }
  Copy

  Example: SSR Component

  import { monoCloud } from "@/lib/monocloud";
  import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
  
  type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
  
  export default function Home({ tokens }: HomeProps) {
    return <pre>Tokens: {JSON.stringify(tokens, null, 2)}</pre>;
  }
  
  export const getServerSideProps: GetServerSideProps = async (context) => {
    const tokens = await monoCloud.getTokens(context.req, context.res);
  
    return {
      props: {
        tokens: tokens ?? null,
      },
    };
  };
  Copy

  Example: Refresh Default Token

  The default token is an access token with scopes set through MONOCLOUD_AUTH_SCOPES or options.defaultAuthParams.scopes, and resources set through MONOCLOUD_AUTH_RESOURCE or options.defaultAuthParams.resource. This token is refreshed when calling getTokens without parameters.

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
    const tokens = await monoCloud.getTokens(req, res, { forceRefresh: true });
  
    res.status(200).json({ accessToken: tokens?.accessToken });
  }
  Copy

  Example: Request new access token for resource(s)

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  The following example shows how to request a new token scoped to two non-exclusive resources.

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    const tokens = await monoCloud.getTokens(req, res, {
      resource: "https://first.example.com https://second.example.com",
      scopes: "read:first read:second shared",
    });
  
    res.status(200).json({ accessToken: tokens?.accessToken });
  }
  Copy

  Example: Request an exclusive token

  Note: Ensure that the resources and scopes are included in the initial authorization flow

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    const tokens = await monoCloud.getTokens(req, res, {
      resource: "https://exclusive.example.com",
      scopes: "read:exclusive shared",
    });
  
    res.status(200).json({ accessToken: tokens?.accessToken });
  }
  Copy

isAuthenticated

• isAuthenticated(): Promise<boolean>

  SSR Components, Actions, Middleware or API Handlers

  Checks if the current user is authenticated.

  Use Case:

  • App Router Server Components (RSC).
  • Server Actions
  • Route Handlers (App Router only).
  • Middleware (App Router and Pages Router).

  Returns Promise<boolean>

  true if the user is authenticated, otherwise false.

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextResponse } from "next/server";
  
  export default async function middleware() {
    const authenticated = await monoCloud.isAuthenticated();
  
    if (!authenticated) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const authenticated = await monoCloud.isAuthenticated();
  
    return NextResponse.json({ authenticated });
  };
  Copy

  Example: React Server Components

  import { monoCloud } from "@/lib/monocloud";
  
  export default async function Home() {
    const authenticated = await monoCloud.isAuthenticated();
  
    return <div>Authenticated: {authenticated.toString()}</div>;
  }
  Copy

  Example: Server Action

  "use server";
  
  import { monoCloud } from "@/lib/monocloud";
  
  export async function checkAuthAction() {
    const authenticated = await monoCloud.isAuthenticated();
  
    return { authenticated };
  }
  Copy

• isAuthenticated(
      req: Request | NextRequest,
      res?: Response | NextResponse<unknown>,
  ): Promise<boolean>

  Middleware/Proxy or Route Handlers

  Checks if the current user is authenticated.

  Use Case:

  • Middleware (for both App and Pages Router).
  • App Router Route Handlers (API routes).
  • Edge functions.

  Parameters

  • req: Request | NextRequest

    NextRequest

  • Optionalres: Response | NextResponse<unknown>

    An optional NextResponse instance. Pass this if you have already initialized a response; otherwise, omit this parameter.

  Returns Promise<boolean>

  true if the user is authenticated, otherwise false.

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const authenticated = await monoCloud.isAuthenticated(req);
  
    if (!authenticated) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: Middleware/Proxy (Custom Response)

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const res = NextResponse.next();
  
    const authenticated = await monoCloud.isAuthenticated(req, res);
  
    if (!authenticated) {
      return new NextResponse("User not signed in", { status: 401 });
    }
  
    res.headers.set("x-authenticated", "true");
  
    return res;
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: API Handler

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const authenticated = await monoCloud.isAuthenticated(req);
  
    return NextResponse.json({ authenticated });
  };
  Copy

  Example: API Handler with NextResponse

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("YOUR CUSTOM RESPONSE");
  
    const authenticated = await monoCloud.isAuthenticated(req, res);
  
    if (authenticated) {
      res.cookies.set("something", "important");
    }
  
    return res;
  };
  Copy

• isAuthenticated(
      req: NextApiRequest | IncomingMessage,
      res: NextApiResponse | ServerResponse<IncomingMessage>,
  ): Promise<boolean>

  Pages Router (Node.js Runtime)

  Checks if the current user is authenticated.

  Parameters

  • req: NextApiRequest | IncomingMessage

    NextApiRequest

  • res: NextApiResponse | ServerResponse<IncomingMessage>

    NextApiResponse

  Returns Promise<boolean>

  true if the user is authenticated, otherwise false.

  Example: API Handler

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  type Data = {
    authenticated: boolean;
  };
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse<Data>
  ) {
    const authenticated = await monoCloud.isAuthenticated(req, res);
  
    res.status(200).json({ authenticated });
  }
  Copy

  Example: SSR Component

  import { monoCloud } from "@/lib/monocloud";
  import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
  
  type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
  
  export default function Home({ authenticated }: HomeProps) {
    return <pre>User is {authenticated ? "logged in" : "guest"}</pre>;
  }
  
  export const getServerSideProps: GetServerSideProps = async (context) => {
    const authenticated = await monoCloud.isAuthenticated(
      context.req,
      context.res
    );
  
    return {
      props: {
        authenticated,
      },
    };
  };
  Copy

isUserInGroup

• isUserInGroup(
      groups: string[],
      options?: IsUserInGroupOptions,
  ): Promise<boolean>

  SSR Components, Actions, Middleware or API Handlers

  Checks if the currently authenticated user is a member of any of the specified groups.

  Use Case:

  • App Router Server Components (RSC).
  • Server Actions
  • Route Handlers (App Router only).
  • Middleware (App Router and Pages Router).

  Parameters

  • groups: string[]

    A list of group names or IDs to check against the user's group memberships.

  • Optionaloptions: IsUserInGroupOptions

    Configuration options.

  Returns Promise<boolean>

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextResponse } from "next/server";
  
  export default async function middleware() {
    const isAdmin = await monoCloud.isUserInGroup(["admin"]);
  
    if (!isAdmin) {
      return new NextResponse("User is not admin", { status: 403 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    const allowed = await monoCloud.isUserInGroup(["admin", "editor"]);
  
    if (!allowed) {
      return new NextResponse("Forbidden", { status: 403 });
    }
  
    return NextResponse.json({ status: "success" });
  };
  Copy

  Example: React Server Components

  import { monoCloud } from "@/lib/monocloud";
  
  export default async function AdminPanel() {
    const isAdmin = await monoCloud.isUserInGroup(["admin"]);
  
    if (!isAdmin) {
      return <div>Access Denied</div>;
    }
  
    return <div>Admin Control Panel</div>;
  }
  Copy

  Example: Server Action

  "use server";
  
  import { monoCloud } from "@/lib/monocloud";
  
  export async function deletePostAction() {
    const canDelete = await monoCloud.isUserInGroup(["admin", "editor"]);
  
    if (!canDelete) {
      return { success: false };
    }
  
    return { success: true };
  }
  Copy

• isUserInGroup(
      req: Request | NextRequest,
      groups: string[],
      options?: IsUserInGroupOptions,
  ): Promise<boolean>

  Middleware/Proxy or Route Handlers

  Checks if the currently authenticated user is a member of any of the specified groups.

  Use Case:

  • Middleware (for both App and Pages Router).
  • App Router Route Handlers (API routes).
  • Edge functions.

  Parameters

  • req: Request | NextRequest

    NextRequest

  • groups: string[]

    A list of group names or IDs to check against the user's group memberships.

  • Optionaloptions: IsUserInGroupOptions

    Configuration options.

  Returns Promise<boolean>

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const isAdmin = await monoCloud.isUserInGroup(req, ["admin"]);
  
    if (!isAdmin) {
      return new NextResponse("User is not admin", { status: 403 });
    }
  
    return NextResponse.next();
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: App Router API Handler

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const isMember = await monoCloud.isUserInGroup(req, ["admin", "editor"]);
  
    return NextResponse.json({ isMember });
  };
  Copy

• isUserInGroup(
      req: Request | NextRequest,
      res: Response | NextResponse<unknown>,
      groups: string[],
      options?: IsUserInGroupOptions,
  ): Promise<boolean>

  Middleware/Proxy or Route Handlers (Custom Response)

  Checks if the currently authenticated user is a member of any of the specified groups.

  Use Case:

  • Middleware (when modifying the response).
  • App Router Route Handlers (when a NextResponse is already initialized).

  Parameters

  • req: Request | NextRequest

    NextRequest

  • res: Response | NextResponse<unknown>

    An optional NextResponse instance. Pass this if you have already initialized a response and want token updates to be applied to it.

  • groups: string[]

    A list of group names or IDs to check against the user's group memberships.

  • Optionaloptions: IsUserInGroupOptions

    Configuration options.

  Returns Promise<boolean>

  Example: Middleware/Proxy

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export default async function middleware(req: NextRequest) {
    const res = NextResponse.next();
  
    const isAdmin = await monoCloud.isUserInGroup(req, res, ["admin"]);
  
    if (!isAdmin) {
      return new NextResponse("User is not admin", { status: 403 });
    }
  
    res.headers.set("x-user", "admin");
  
    return res;
  }
  
  export const config = {
    matcher: [
      "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ],
  };
  Copy

  Example: API Handler with NextResponse

  import { NextRequest, NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async (req: NextRequest) => {
    const res = new NextResponse("Restricted Content");
  
    const allowed = await monoCloud.isUserInGroup(req, res, ["admin"]);
  
    if (!allowed) {
      return new NextResponse("Not Allowed", res);
    }
  
    return res;
  };
  Copy

• isUserInGroup(
      req: NextApiRequest | IncomingMessage,
      res: NextApiResponse | ServerResponse<IncomingMessage>,
      groups: string[],
      options?: IsUserInGroupOptions,
  ): Promise<boolean>

  Pages Router (Node.js Runtime)

  Checks if the currently authenticated user is a member of any of the specified groups.

  Parameters

  • req: NextApiRequest | IncomingMessage

    The NextApiRequest or IncomingMessage.

  • res: NextApiResponse | ServerResponse<IncomingMessage>

    The NextApiResponse or ServerResponse.

  • groups: string[]

    A list of group names or IDs to check against the user's group memberships.

  • Optionaloptions: IsUserInGroupOptions

    Configuration options.

  Returns Promise<boolean>

  Example: API Route

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
  ) {
    const isAdmin = await monoCloud.isUserInGroup(req, res, ["admin"]);
  
    if (!isAdmin) {
      return res.status(403).json({ error: "Forbidden" });
    }
  
    res.status(200).json({ message: "Welcome Admin" });
  }
  Copy

  Example: SSR Component

  import { monoCloud } from "@/lib/monocloud";
  import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
  
  type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
  
  export default function Home({ isAdmin }: HomeProps) {
    return <div>User is admin: {isAdmin.toString()}</div>;
  }
  
  export const getServerSideProps: GetServerSideProps = async (context) => {
    const isAdmin = await monoCloud.isUserInGroup(context.req, context.res, [
      "admin",
    ]);
  
    return {
      props: {
        isAdmin,
      },
    };
  };
  Copy

monoCloudAuth

• monoCloudAuth(options?: MonoCloudAuthOptions): MonoCloudAuthHandler

  Creates a Next.js API route handler (for both Pages Router and App Router) that processes all MonoCloud authentication endpoints (/signin, /callback, /userinfo, /signout).

  Parameters

  • Optionaloptions: MonoCloudAuthOptions

    Authentication configuration routes.

    Note: If you are already using authMiddleware(), you typically do not need this API route handler. This function is intended for applications where middleware cannot be used—such as statically generated (SSG) deployments that still require server-side authentication flows.

  Returns MonoCloudAuthHandler

  Example: App Router

  // app/api/auth/[...monocloud]/route.ts
  
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = monoCloud.monoCloudAuth();
  Copy

  Example: App Router with Response

  import { monoCloud } from "@/lib/monocloud";
  import { NextRequest, NextResponse } from "next/server";
  
  export const GET = (req: NextRequest) => {
    const authHandler = monoCloud.monoCloudAuth();
  
    const res = new NextResponse();
  
    res.cookies.set("last_auth_requested", `${Date.now()}`);
  
    return authHandler(req, res);
  };
  Copy

  Example: Pages Router

  // pages/api/auth/[...monocloud].ts
  
  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.monoCloudAuth();
  Copy

  Example: Page Router with Response

  import { monoCloud } from "@/lib/monocloud";
  import { NextApiRequest, NextApiResponse } from "next";
  
  export default function handler(req: NextApiRequest, res: NextApiResponse) {
    const authHandler = monoCloud.monoCloudAuth();
  
    res.setHeader("last_auth_requested", `${Date.now()}`);
  
    return authHandler(req, res);
  }
  Copy

protect

• protect(options?: ProtectOptions): Promise<void>

  Redirects the user to the sign-in flow if they are not authenticated.

  This helper is App Router only and is designed for server environments (server components, route handlers, and server actions).

  Parameters

  • Optionaloptions: ProtectOptions

    Options to customize the sign-in.

  Returns Promise<void>

  Example: React Server Component

  import { monoCloud } from "@/lib/monocloud";
  
  export default async function Home() {
    await monoCloud.protect();
  
    return <>You are signed in.</>;
  }
  Copy

  Example: API Handler

  import { NextResponse } from "next/server";
  import { monoCloud } from "@/lib/monocloud";
  
  export const GET = async () => {
    await monoCloud.protect();
  
    return NextResponse.json({ secret: "ssshhhh!!!" });
  };
  Copy

  Example: Server Action

  "use server";
  
  import { monoCloud } from "@/lib/monocloud";
  
  export async function getMessage() {
    await monoCloud.protect();
  
    return { secret: "sssshhhhh!!!" };
  }
  Copy

protectApi

• protectApi(
      handler: AppRouterApiHandlerFn,
      options?: ProtectApiAppOptions,
  ): AppRouterApiHandlerFn

  App Router

  Secures Next.js App Router APIs. It ensures only authenticated (and optionally authorized) requests can access the route.

  Parameters

  • handler: AppRouterApiHandlerFn

    The api route handler function to protect

  • Optionaloptions: ProtectApiAppOptions

    App Router protectApi() configuration options

  Returns AppRouterApiHandlerFn

  Protected route handler

  Example

  import { monoCloud } from "@/lib/monocloud";
  import { NextResponse } from "next/server";
  
  export const GET = monoCloud.protectApi(async () => {
    return NextResponse.json({
      message: "You accessed a protected endpoint",
    });
  });
  Copy

• protectApi(
      handler: NextApiHandler,
      options?: ProtectApiPageOptions,
  ): NextApiHandler

  Pages Router

  Secures Next.js Pages Router APIs. It ensures only authenticated (and optionally authorized) requests can access the route.

  Parameters

  • handler: NextApiHandler

    The api route handler function to protect

  • Optionaloptions: ProtectApiPageOptions

    Pages Router protectApi() configuration options

  Returns NextApiHandler

  Protected route handler

  Example

  import { monoCloud } from "@/lib/monocloud";
  import type { NextApiRequest, NextApiResponse } from "next";
  
  export default monoCloud.protectApi(
    async (req: NextApiRequest, res: NextApiResponse) => {
      return res.json({
        message: "You accessed a protected endpoint",
      });
    }
  );
  Copy

protectPage

• protectPage(
      component: ProtectedAppServerComponent,
      options?: ProtectAppPageOptions,
  ): AppRouterPageHandler

  App Router

  Restricts access to server-rendered pages in your Next.js App Router application, ensures that only authenticated (and optionally authorized) users can view the page.

  Note⚠️ - When using groups to protect a page, 'Access Denied' is rendered by default when the user does not have enough permissions. To display a custom component, pass the onAccessDenied parameter.

  Parameters

  • component: ProtectedAppServerComponent

    The App Router server component that protectPage wraps and secures

  • Optionaloptions: ProtectAppPageOptions

    App Router protectPage() configuration options

  Returns AppRouterPageHandler

  A protected page handler.

  Example

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.protectPage(async function Home({ user }) {
   return <>Hi {user.email}. You accessed a protected page.</>;
  });
  Copy

  Example: App Router with options

  import { monoCloud } from "@/lib/monocloud";
  
  export default monoCloud.protectPage(
    async function Home({ user }) {
      return <>Hi {user.email}. You accessed a protected page.</>;
    },
    {
      returnUrl: "/dashboard",
      groups: ["admin"],
    }
  );
  Copy

• protectPage<
      P extends Record<string, any> = Record<string, any>,
      Q extends ParsedUrlQuery = ParsedUrlQuery,
  >(
      options?: ProtectPagePageOptions<P, Q>,
  ): ProtectPagePageReturnType<P, Q>

  Pages Router

  Restricts access to server-rendered pages in your Next.js Pages Router application, ensures that only authenticated (and optionally authorized) users can view the page.

  Note⚠️ - When using groups to protect a page, the page will be rendered even if the user does not have enough permissions. You should check the props for accessDenied boolean value to determine whether the user is allowed to accesss the page. Alternatively, you can pass onAccessDenied parameter to return custom props.

  Type Parameters

  • P extends Record<string, any> = Record<string, any>

    The type of parameters accepted by the page handler.

  • Q extends ParsedUrlQuery = ParsedUrlQuery

    The type of query parameters parsed from the URL.

  Parameters

  • Optionaloptions: ProtectPagePageOptions<P, Q>

    Pages Router protectPage() configuration options

  Returns ProtectPagePageReturnType<P, Q>

  A protected page handler.

  Example

  import { monoCloud } from "@/lib/monocloud";
  import { InferGetServerSidePropsType } from "next";
  
  export default function Home({
    user,
  }: InferGetServerSidePropsType<typeof getServerSideProps>) {
    return <>Hi {user.email}. You accessed a protected page.</>;
  }
  
  export const getServerSideProps = monoCloud.protectPage();
  Copy

  Example: Pages Router with options

  import { monoCloud } from "@/lib/monocloud";
  import { GetServerSidePropsContext, InferGetServerSidePropsType } from "next";
  
  export default function Home({
    user,
    url,
  }: InferGetServerSidePropsType<typeof getServerSideProps>) {
    console.log(url);
    return <div>Hi {user?.email}. You accessed a protected page.</div>;
  }
  
  export const getServerSideProps = monoCloud.protectPage({
    returnUrl: "/dashboard",
    groups: ["admin"],
    getServerSideProps: async (context: GetServerSidePropsContext) => ({
      props: { url: context.resolvedUrl },
    }),
  });
  Copy