Function: isUserInGroup

Call Signature

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

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

The groups parameter accepts group identifiers (IDs or names).

The authenticated user's session may contain groups represented as:

Group IDs
Group names
Group objects (for example, { id: string; name: string })

Matching is always performed against the group's ID and name, regardless of how the group is represented in the session.

Parameters

Parameter	Type	Description
`groups`	`string`[]	Group IDs or names to check against the user's group memberships.
`options?`	`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.

Examples

src/app/page.tsx

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

export default async function AdminPanel() {
  const isAdmin = await isUserInGroup(["admin"]);

  if (!isAdmin) {
    return <div>Access Denied</div>;
  }

  return <div>Admin Control Panel</div>;
}

Call Signature

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

Checks group membership using an explicit Web or Next.js request.

Use this overload when you already have access to a Request or NextRequest (for example, in Middleware or Route Handlers).

Parameters

Parameter	Type	Description
`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.
`options?`	`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.

Examples

src/proxy.ts

import { isUserInGroup } from "@monocloud/auth-nextjs";
import { NextRequest, NextResponse } from "next/server";

export default async function proxy(req: NextRequest) {
  const isAdmin = await isUserInGroup(req, ["admin"]);

  if (!isAdmin) {
    return new NextResponse("User is not admin", { status: 403 });
  }

  return NextResponse.next();
}

Call Signature

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

Checks group membership using an explicit request and response.

Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.

Parameters

Parameter	Type	Description
`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.
`options?`	`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.

Examples

src/proxy.ts

import { isUserInGroup } from "@monocloud/auth-nextjs";
import { NextRequest, NextResponse } from "next/server";

export default async function proxy(req: NextRequest) {
  const res = NextResponse.next();

  const isAdmin = await isUserInGroup(req, res, ["admin"]);

  if (!isAdmin) {
    return new NextResponse("User is not admin", { status: 403 });
  }

  res.headers.set("x-user", "admin");

  return res;
}

Call Signature

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

Checks group membership in the Pages Router or Node.js runtime.

Use this overload in API routes or getServerSideProps, where Node.js request and response objects are available.

Parameters

Parameter	Type	Description
`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.
`options?`	`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.

Examples

src/pages/index.tsx

import { isUserInGroup } from "@monocloud/auth-nextjs";
import { GetServerSideProps } from "next";

type Props = {
  isAdmin: boolean;
};

export default function Home({ isAdmin }: Props) {
  return <div>User is admin: {isAdmin.toString()}</div>;
}

export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
  const isAdmin = await isUserInGroup(ctx.req, ctx.res, ["admin"]);

  return {
    props: {
      isAdmin
    }
  };
};