Class MonoCloudNextClient

MonoCloudNextClient is the core SDK entry point for integrating MonoCloud authentication into a Next.js application.

It provides:

Authentication middleware
Route protection helpers
Session and token access
Redirect utilities
Server-side enforcement helpers

1. Add environment variables

MONOCLOUD_AUTH_TENANT_DOMAIN=<tenant-domain>
MONOCLOUD_AUTH_CLIENT_ID=<client-id>
MONOCLOUD_AUTH_CLIENT_SECRET=<client-secret>
MONOCLOUD_AUTH_SCOPES=openid profile email
MONOCLOUD_AUTH_APP_URL=http://localhost:3000
MONOCLOUD_AUTH_COOKIE_SECRET=<cookie-secret>

2. Register middleware

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

export default authMiddleware();

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

Advanced usage

Create a shared client instance

By default, the SDK exposes function exports (for example, authMiddleware(), getSession(), getTokens()) that internally use a shared singleton MonoCloudNextClient.

Create your own MonoCloudNextClient instance when you need multiple configurations, dependency injection, or explicit control over initialization.

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

export const monoCloud = new MonoCloudNextClient();

Using instance methods

Once you create a client instance, call methods directly on it instead of using the default function exports.

import { monoCloud } from "@/monocloud";

export default async function Page() {
  const session = await monoCloud.getSession();

  if (!session) {
    return <>Not signed in</>;
  }

  return <>Hello {session.user.name}</>;
}

Using constructor options

When configuration is provided through both constructor options and environment variables, the values passed to the constructor take precedence. Environment variables are used only for options that are not explicitly supplied.

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

export const monoCloud = new MonoCloudNextClient({
  tenantDomain: "<tenant-domain>",
  clientId: "<client-id>",
  clientSecret: "<client-secret>",
  appUrl: "http://localhost:3000",
  cookieSecret: "<cookie-secret>",
  defaultAuthParams: {
    scopes: "openid profile email",
  },
});

Modifying default routes

If you customize any of the default auth route paths:

Also set the corresponding NEXT_PUBLIC_ environment variables so client-side helpers (for example <SignIn />, <SignOut />, and useAuth()) can discover the correct URLs.
Update the Application URLs in your MonoCloud Dashboard to match the new paths.

Example:

MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback
NEXT_PUBLIC_MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback

When routes are overridden, the Redirect URI configured in the dashboard must reflect the new path. For example, during local development:

http://localhost:3000/api/custom_callback

Index

Constructors

constructor

new MonoCloudNextClient(options?: MonoCloudOptions): MonoCloudNextClient
Creates a new client instance.
Parameters
- Optionaloptions: MonoCloudOptions
  Optional configuration for initializing the MonoCloud client. If not provided, settings are automatically resolved from environment variables.
Returns MonoCloudNextClient
- Defined in packages/nextjs/src/monocloud-next-client.ts:223

Accessors

coreClient

get coreClient(): MonoCloudCoreClient
This exposes the framework-agnostic MonoCloud client used internally by the Next.js SDK. Use it if you need access to lower-level functionality not directly exposed by MonoCloudNextClient.

Returns MonoCloudCoreClient
Returns the underlying Node client instance.
- Defined in packages/nextjs/src/monocloud-next-client.ts:205

oidcClient

get oidcClient(): MonoCloudOidcClient
This is intended for advanced scenarios requiring direct control over the authorization or token flow.

Returns MonoCloudOidcClient
Returns the underlying OIDC client used for OpenID Connect operations.
- Defined in packages/nextjs/src/monocloud-next-client.ts:214

Methods

authMiddleware

authMiddleware(options?: MonoCloudMiddlewareOptions): NextMiddleware
Parameters
- Optionaloptions: MonoCloudMiddlewareOptions
  Optional configuration that controls how authentication is enforced (for example, redirect behavior, route matching, or custom handling of unauthenticated requests).
Returns NextMiddleware
Returns a Next.js middleware result (NextResponse, redirect, or undefined to continue processing).

See
authMiddleware for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:719
authMiddleware(
request: NextRequest,
event: NextFetchEvent,
): NextMiddlewareResult | Promise<NextMiddlewareResult>
Parameters
- request: NextRequest
  Incoming Next.js middleware request used to resolve authentication state.
- event: NextFetchEvent
  Next.js middleware event providing lifecycle hooks such as waitUntil.
Returns NextMiddlewareResult | Promise<NextMiddlewareResult>
Returns a Next.js middleware result (NextResponse, redirect, or undefined to continue processing).

See
authMiddleware for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:729

getSession

getSession(): Promise<MonoCloudSession | undefined>
Returns Promise<MonoCloudSession | undefined>
Returns the resolved session, or undefined if none exists.

See
getSession for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:971
getSession(
req: Request | NextRequest,
res?: Response | NextResponse<unknown>,
): Promise<MonoCloudSession | undefined>
Parameters
- req: Request | NextRequest
  Incoming request used to read authentication cookies and headers to resolve the current user's session.
- Optionalres: Response | NextResponse<unknown>
  Optional response to update if session resolution requires refreshed authentication cookies or headers.
Returns Promise<MonoCloudSession | undefined>
Returns the resolved session, or undefined if none exists.

See
getSession for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:979
getSession(
req: NextApiRequest | IncomingMessage,
res: NextApiResponse | ServerResponse<IncomingMessage>,
): Promise<MonoCloudSession | undefined>
Parameters
- req: NextApiRequest | IncomingMessage
  Incoming Node.js request used to read authentication cookies and resolve the current user's session.
- res: NextApiResponse | ServerResponse<IncomingMessage>
  Outgoing Node.js response used to apply refreshed authentication cookies when required.
Returns Promise<MonoCloudSession | undefined>
Returns the resolved session, or undefined if none exists.

See
getSession for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:990

getTokens

getTokens(options?: GetTokensOptions): Promise<MonoCloudTokens>
Parameters
- Optionaloptions: GetTokensOptions
  Optional configuration controlling refresh behavior and resource/scope selection.
Returns Promise<MonoCloudTokens>
The current user's tokens, refreshed if necessary.

See
getTokens for full docs and examples.

Throws
MonoCloudValidationError If no valid session exists.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1022
getTokens(
req: Request | NextRequest,
options?: GetTokensOptions,
): Promise<MonoCloudTokens>
Parameters
- req: Request | NextRequest
  Incoming request used to resolve authentication from cookies and headers.
- Optionaloptions: GetTokensOptions
  Optional configuration controlling refresh behavior and resource/scope selection.
Returns Promise<MonoCloudTokens>
The current user's tokens, refreshed if necessary.

See
getTokens for full docs and examples.

Throws
MonoCloudValidationError If no valid session exists.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1031
getTokens(
    req: Request | NextRequest,
    res: Response | NextResponse<unknown>,
    options?: GetTokensOptions,
): Promise<MonoCloudTokens>
Parameters
- req: Request | NextRequest
  Incoming request used to resolve authentication from cookies and headers.
- res: Response | NextResponse<unknown>
  Existing response to update with refreshed authentication cookies or headers.
- Optionaloptions: GetTokensOptions
  Optional configuration controlling refresh behavior and resource/scope selection.
Returns Promise<MonoCloudTokens>
The current user's tokens, refreshed if necessary.

See
getTokens for full docs and examples.

Throws
MonoCloudValidationError If no valid session exists.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1044
getTokens(
    req: NextApiRequest | IncomingMessage,
    res: NextApiResponse | ServerResponse<IncomingMessage>,
    options?: GetTokensOptions,
): Promise<MonoCloudTokens>
Parameters
- req: NextApiRequest | IncomingMessage
  Incoming Node.js request used to resolve authentication from cookies.
- res: NextApiResponse | ServerResponse<IncomingMessage>
  Outgoing Node.js response used to apply refreshed authentication cookies when required.
- Optionaloptions: GetTokensOptions
  Optional configuration controlling refresh behavior and resource/scope selection.
Returns Promise<MonoCloudTokens>
The current user's tokens, refreshed if necessary.

See
getTokens for full docs and examples.

Throws
MonoCloudValidationError If no valid session exists.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1058

isAuthenticated

isAuthenticated(): Promise<boolean>
Returns Promise<boolean>
Returns true if a valid session exists; otherwise false.

See
isAuthenticated for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1117
isAuthenticated(
req: Request | NextRequest,
res?: Response | NextResponse<unknown>,
): Promise<boolean>
Parameters
- req: Request | NextRequest
  Incoming request used to resolve authentication from cookies and headers.
- Optionalres: Response | NextResponse<unknown>
  Optional response to update if refreshed authentication cookies or headers are required.
Returns Promise<boolean>
Returns true if a valid session exists; otherwise false.

See
isAuthenticated for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1125
isAuthenticated(
req: NextApiRequest | IncomingMessage,
res: NextApiResponse | ServerResponse<IncomingMessage>,
): Promise<boolean>
Parameters
- req: NextApiRequest | IncomingMessage
  Incoming Node.js request used to resolve authentication from cookies.
- res: NextApiResponse | ServerResponse<IncomingMessage>
  Outgoing Node.js response used to apply refreshed authentication cookies when required.
Returns Promise<boolean>
Returns true if a valid session exists; otherwise false.

See
isAuthenticated for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1136

isUserInGroup

isUserInGroup(
groups: string[],
options?: IsUserInGroupOptions,
): Promise<boolean>
Parameters
- groups: string[]
  Group IDs or names to check against the user's group memberships.
- Optionaloptions: IsUserInGroupOptions
  Optional configuration controlling how group membership is evaluated.
Returns Promise<boolean>
Returns true if the user belongs to at least one specified group; otherwise false.

See
isUserInGroup for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1261
isUserInGroup(
    req: Request | NextRequest,
    groups: string[],
    options?: IsUserInGroupOptions,
): Promise<boolean>
Parameters
- req: Request | NextRequest
  Incoming request used to resolve authentication from cookies and headers.
- groups: string[]
  Group IDs or names to check against the user's group memberships.
- Optionaloptions: IsUserInGroupOptions
  Optional configuration controlling how group membership is evaluated.
Returns Promise<boolean>
Returns true if the user belongs to at least one specified group; otherwise false.

See
isUserInGroup for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1273
isUserInGroup(
    req: Request | NextRequest,
    res: Response | NextResponse<unknown>,
    groups: string[],
    options?: IsUserInGroupOptions,
): Promise<boolean>
Parameters
- req: Request | NextRequest
  Incoming request used to resolve authentication from cookies and headers.
- res: Response | NextResponse<unknown>
  Existing response to update with refreshed authentication cookies or headers when required.
- groups: string[]
  Group IDs or names to check against the user's group memberships.
- Optionaloptions: IsUserInGroupOptions
  Optional configuration controlling how group membership is evaluated.
Returns Promise<boolean>
Returns true if the user belongs to at least one specified group; otherwise false.

See
isUserInGroup for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1287
isUserInGroup(
    req: NextApiRequest | IncomingMessage,
    res: NextApiResponse | ServerResponse<IncomingMessage>,
    groups: string[],
    options?: IsUserInGroupOptions,
): Promise<boolean>
Parameters
- req: NextApiRequest | IncomingMessage
  Incoming Node.js request used to resolve authentication from cookies.
- res: NextApiResponse | ServerResponse<IncomingMessage>
  Outgoing Node.js response used to apply refreshed authentication cookies when required.
- groups: string[]
  Group IDs or names to check against the user's group memberships.
- Optionaloptions: IsUserInGroupOptions
  Optional configuration controlling how group membership is evaluated.
Returns Promise<boolean>
Returns true if the user belongs to at least one specified group; otherwise false.

See
isUserInGroup for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1302

monoCloudAuth

monoCloudAuth(options?: MonoCloudAuthOptions): MonoCloudAuthHandler
Parameters
- Optionaloptions: MonoCloudAuthOptions
  Optional configuration for the auth handler.
Returns MonoCloudAuthHandler
Returns a Next.js-compatible handler for App Router route handlers or Pages Router API routes.

See
monoCloudAuth for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:239

protect

protect(options?: ProtectOptions): Promise<void>
Parameters
- Optionaloptions: ProtectOptions
  Optional configuration for redirect behavior (for example, return URL or sign-in parameters).
Returns Promise<void>
Resolves if the user is authenticated; otherwise triggers a redirect.

See
protect for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1167

protectApi

protectApi(
handler: AppRouterApiHandlerFn,
options?: ProtectApiAppOptions,
): AppRouterApiHandlerFn
Parameters
- handler: AppRouterApiHandlerFn
  The route handler to protect.
- Optionaloptions: ProtectApiAppOptions
  Optional configuration controlling authentication and authorization behavior.
Returns AppRouterApiHandlerFn
Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.

See
protectApi for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:569
protectApi(
handler: NextApiHandler,
options?: ProtectApiPageOptions,
): NextApiHandler
Parameters
- handler: NextApiHandler
  The route handler to protect.
- Optionaloptions: ProtectApiPageOptions
  Optional configuration controlling authentication and authorization behavior.
Returns NextApiHandler
Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.

See
protectApi for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:580

protectPage

protectPage(
component: ProtectedAppServerComponent,
options?: ProtectAppPageOptions,
): AppRouterPageHandler
Parameters
- component: ProtectedAppServerComponent
  The App Router server component to protect.
- Optionaloptions: ProtectAppPageOptions
  Optional configuration for authentication, authorization, and custom access handling (onAccessDenied, onGroupAccessDenied).
Returns AppRouterPageHandler
A wrapped page component that enforces authentication before rendering.

See
protectPage for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:288
protectPage<
    P extends Record<string, any> = Record<string, any>,
    Q extends ParsedUrlQuery = ParsedUrlQuery,
>(
    options?: ProtectPagePageOptions<P, Q>,
): ProtectPagePageReturnType<P, Q>
Type Parameters
- P extends Record<string, any> = Record<string, any>
  Props returned from getServerSideProps.
- Q extends ParsedUrlQuery = ParsedUrlQuery
  Query parameters parsed from the URL.
Parameters
- Optionaloptions: ProtectPagePageOptions<P, Q>
  Optional configuration for authentication, authorization, and custom access handling (onAccessDenied, onGroupAccessDenied).
Returns ProtectPagePageReturnType<P, Q>
A getServerSideProps wrapper that enforces authentication before executing the page logic.

See
protectPage for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:300

redirectToSignIn

redirectToSignIn(options?: RedirectToSignInOptions): Promise<void>
Parameters
- Optionaloptions: RedirectToSignInOptions
  Optional configuration for the redirect, such as returnUrl or additional sign-in parameters.
Returns Promise<void>
Never resolves. Triggers a redirect to the sign-in flow.

See
redirectToSignIn for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1392

redirectToSignOut

redirectToSignOut(options?: RedirectToSignOutOptions): Promise<void>
Parameters
- Optionaloptions: RedirectToSignOutOptions
  Optional configuration for the redirect, such as postLogoutRedirectUri or additional sign-out parameters.
Returns Promise<void>
Never resolves. Triggers a redirect to the sign-out flow.

See
redirectToSignOut for full docs and examples.
- Defined in packages/nextjs/src/monocloud-next-client.ts:1464

Class MonoCloudNextClient

1. Add environment variables

2. Register middleware

Advanced usage

Create a shared client instance

Using instance methods

Using constructor options

Modifying default routes

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns MonoCloudNextClient

Accessors

coreClient

Returns MonoCloudCoreClient

oidcClient

Returns MonoCloudOidcClient

Methods

authMiddleware

Parameters

Returns NextMiddleware

See

Parameters

Returns NextMiddlewareResult | Promise<NextMiddlewareResult>

See

getSession

Returns Promise<MonoCloudSession | undefined>

See

Parameters

Returns Promise<MonoCloudSession | undefined>

See

Parameters

Returns Promise<MonoCloudSession | undefined>

See

getTokens

Parameters

Returns Promise<MonoCloudTokens>

See

Throws

Parameters

Returns Promise<MonoCloudTokens>

See

Throws

Parameters

Returns Promise<MonoCloudTokens>

See

Throws

Parameters

Returns Promise<MonoCloudTokens>

See

Throws

isAuthenticated

Returns Promise<boolean>

See

Parameters

Returns Promise<boolean>

See

Parameters

Returns Promise<boolean>

See

isUserInGroup

Parameters

Returns Promise<boolean>

See

Parameters

Returns Promise<boolean>

See

Parameters

Returns Promise<boolean>

See

Parameters

Returns Promise<boolean>

See

monoCloudAuth

Parameters

Returns MonoCloudAuthHandler