@authgear/nextjs

v0.4.0

Published

10 days ago

Authgear SDK for Next.js 16 - OAuth authentication, session management, and JWT verification

0High
0Medium
0Low

authgear nextjs authentication oauth oidc jwt

Authgear SDK for Next.js

With Authgear SDK for Next.js, you can easily integrate authentication features into your Next.js application — covering both the frontend and backend in one package. In most cases, it involves just a few lines of code to enable multiple authentication methods, such as social logins, passwordless, biometrics logins, one-time-password (OTP) with SMS/WhatsApp, and multi-factor authentication (MFA).

Quick links — 📚 Documentation · 🏁 Getting Started · 🛠️ Troubleshooting · 👥 Contributing

What is Authgear?

Authgear is a highly adaptable identity-as-a-service (IDaaS) platform for web and mobile applications. Authgear makes user authentication easier and faster to implement by integrating it into various types of applications — from single-page web apps to mobile applications to API services.

Key Features

Zero-trust authentication architecture with OpenID Connect (OIDC) standard.
Easy-to-use interfaces for user registration and login, including email, phone, username as login ID, and password, OTP, magic links, etc.
Support for a wide range of identity providers, such as Google, Apple, and Azure Active Directory.
Support for Passkeys, biometric login, and Multi-Factor Authentication (MFA) such as SMS/email-based verification and authenticator apps with TOTP.

Requirements

Next.js >= 16.0.0
React >= 19.0.0
Node.js >= 18

Installation

npm install @authgear/nextjs

Getting Started

For a complete tutorial, see the Next.js integration guide on Authgear Docs, or explore the example project on GitHub.

1. Configure Authgear

Create a config object. The sessionSecret must be at least 32 characters and should be stored in an environment variable.

// lib/authgear.ts
import type { AuthgearConfig } from "@authgear/nextjs";

export const authgearConfig: AuthgearConfig = {
  endpoint: process.env.AUTHGEAR_ENDPOINT!,       // e.g. "https://myapp.authgear.cloud"
  clientID: process.env.AUTHGEAR_CLIENT_ID!,
  redirectURI: process.env.AUTHGEAR_REDIRECT_URI!,   // e.g. "http://localhost:3000/api/auth/callback"
  sessionSecret: process.env.SESSION_SECRET!,         // min 32 chars
};

2. Add the Route Handler

Create a catch-all route to handle all auth endpoints (/api/auth/login, /api/auth/callback, /api/auth/logout, /api/auth/refresh, /api/auth/userinfo).

// app/api/auth/[...authgear]/route.ts
import { createAuthgearHandlers } from "@authgear/nextjs";
import { authgearConfig } from "@/lib/authgear";

export const { GET, POST } = createAuthgearHandlers(authgearConfig);

3. Add the Provider (Client Components)

Wrap your app with AuthgearProvider to enable client-side hooks and components.

// app/layout.tsx
import { AuthgearProvider } from "@authgear/nextjs/client";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AuthgearProvider>{children}</AuthgearProvider>
      </body>
    </html>
  );
}

4. Protect Routes with the Proxy (Next.js 16)

Create a proxy.ts file at the root of your project to automatically redirect unauthenticated users and inject auth headers.

// proxy.ts
import { createAuthgearProxy } from "@authgear/nextjs/proxy";
import { authgearConfig } from "@/lib/authgear";

export const proxy = createAuthgearProxy({
  ...authgearConfig,
  protectedPaths: ["/dashboard/*", "/profile/*"],
});

Usage

Client Components

Use the useAuthgear hook or the built-in buttons:

"use client";

import { useAuthgear, SignInButton, SignOutButton } from "@authgear/nextjs/client";

export function NavBar() {
  const { isAuthenticated, isLoaded, user } = useAuthgear();

  if (!isLoaded) return null;

  return isAuthenticated ? (
    <div>
      <span>Welcome, {user?.email}</span>
      <SignOutButton />
    </div>
  ) : (
    <SignInButton />
  );
}

Server Components

Use currentUser() to get the authenticated user in Server Components and Route Handlers.

// app/dashboard/page.tsx
import { currentUser } from "@authgear/nextjs/server";
import { authgearConfig } from "@/lib/authgear";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const user = await currentUser(authgearConfig);
  if (!user) redirect("/api/auth/login?returnTo=/dashboard");

  return <h1>Hello, {user.email}</h1>;
}

Protecting API Routes with JWT

Use verifyAccessToken() to validate a Bearer token in API routes.

// app/api/me/route.ts
import { verifyAccessToken } from "@authgear/nextjs/server";
import { authgearConfig } from "@/lib/authgear";
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const authHeader = request.headers.get("Authorization");
  const token = authHeader?.replace("Bearer ", "");
  if (!token) return NextResponse.json({ error: "unauthorized" }, { status: 401 });

  try {
    const payload = await verifyAccessToken(token, authgearConfig);
    return NextResponse.json({ sub: payload.sub });
  } catch {
    return NextResponse.json({ error: "invalid_token" }, { status: 401 });
  }
}

Reading the Session in Server Actions

Use auth() to get the session (including a fresh access token) without fetching user info. This is the right choice for Server Actions that need to call a downstream API on behalf of the user — auth() will auto-refresh the token if expired before returning it.

"use server";
import { auth, SessionState } from "@authgear/nextjs/server";
import { authgearConfig } from "@/lib/authgear";

export async function callMyApiAction() {
  const session = await auth(authgearConfig);
  if (session.state !== SessionState.Authenticated || !session.accessToken) {
    throw new Error("Not authenticated");
  }

  // session.accessToken is always fresh — auto-refreshed if it was expired
  const res = await fetch("https://api.example.com/data", {
    headers: { Authorization: `Bearer ${session.accessToken}` },
  });
  return res.json();
}

API Reference

`@authgear/nextjs`

| Export | Kind | Values | Description | |---|---|---|---| | createAuthgearHandlers(config) | Function | — | Returns { GET, POST } for app/api/auth/[...authgear]/route.ts | | PromptOption | Enum | "login" | "none" | Convenience constants for the OIDC prompt parameter. Pass to signIn({ prompt: PromptOption.Login }) to force the login form for a specific sign-in call. |

`@authgear/nextjs/server`

| Export | Description | |---|---| | auth(config) | Returns the current Session, auto-refreshes access token if expired | | currentUser(config) | Returns UserInfo \| null, auto-refreshes access token if expired | | verifyAccessToken(token, config) | Verifies a JWT Bearer token with JWKS, returns JWTPayload | | getOpenURL(page, config) | Returns a URL to open an Authgear page (e.g. Page.Settings) with the user pre-authenticated |

`@authgear/nextjs/client`

| Export | Description | |---|---| | <AuthgearProvider> | React context provider, must wrap the app | | useAuthgear() | Returns { state, user, isLoaded, isAuthenticated, signIn, signOut, openPage } | | useUser() | Returns UserInfo \| null | | <SignInButton> | Button that calls signIn() on click | | <SignOutButton> | Button that calls signOut() on click | | <UserSettingsButton> | Button that opens Authgear account settings in a new tab |

AuthgearProvider props:

| Prop | Default | Description | |---|---|---| | openPagePath | "/api/auth/open" | Route used by openPage() and <UserSettingsButton> to pre-authenticate and redirect to an Authgear page |

`SignInOptions`

Options accepted by signIn() (from useAuthgear()) and the signInOptions prop on <SignInButton>.

| Field | Type | Required | Default | Description | |---|---|---|---|---| | returnTo | string | No | — | Path to redirect to after sign-in. | | loginPath | string | No | "/api/auth/login" | Override the login route for this call. | | prompt | string | No | — | OIDC prompt value for this sign-in call. Use PromptOption.Login to force the login form. Overrides the global isSSOEnabled setting. |

`@authgear/nextjs/proxy`

| Export | Description | |---|---| | createAuthgearProxy(options) | Returns a Next.js 16 proxy() function |

createAuthgearProxy options (extends AuthgearConfig):

| Option | Default | Description | |---|---|---| | protectedPaths | [] | Paths requiring auth, supports * suffix (e.g. "/dashboard/*") | | publicPaths | ["/api/auth/*"] | Paths always allowed through | | loginPath | "/api/auth/login" | Where to redirect unauthenticated users |

`AuthgearConfig`

| Field | Required | Description | |---|---|---| | endpoint | ✓ | Authgear endpoint, e.g. "https://myapp.authgear.cloud" | | clientID | ✓ | OAuth client ID | | redirectURI | ✓ | OAuth callback URL, e.g. "http://localhost:3000/api/auth/callback" | | sessionSecret | ✓ | Secret for encrypting session cookie (min 32 chars) | | postLogoutRedirectURI | | Where to redirect after logout. Defaults to "/" | | scopes | | OAuth scopes. Defaults to ["openid", "offline_access", "https://authgear.com/scopes/full-userinfo"] | | isSSOEnabled | | When false, always shows the Authgear login form (prompt=login), even if the user has an existing Authgear session. Recommended for single-app deployments. Defaults to true | | cookieName | | Session cookie name. Defaults to "authgear.session" |

Roadmap

This SDK is actively maintained. Feature requests and contributions are welcome via GitHub Issues.

Documentation

SDK Documentation: https://authgear.github.io/authgear-sdk-nextjs/
Learn how to set up an Authgear application at https://docs.authgear.com/
Learn how to manage your users through the Admin API

Troubleshooting

Please check out the Get Help section for solutions to common issues.

Raise an Issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Contributing

Anyone who wishes to contribute to this project, whether documentation, features, bug fixes, code cleanup, testing, or code reviews, is very much encouraged to do so.

To join, raise your hand on the Authgear Discord server or the GitHub discussions board.

git clone [email protected]:authgear/authgear-sdk-nextjs.git
cd authgear-sdk-nextjs
npm install
npm test