Next.js SDK

@namoidhq/nextjs is the confidential App Router adapter for NamoID Hosted Auth. It keeps transaction state, the Client Secret, PKCE verifier, callback validation, refresh tokens, and application sessions in trusted server code.

This guide requires @namoidhq/nextjs 3.0.0 or later.

Install

pnpm add @namoidhq/nextjs @namoidhq/js

Configure once

// lib/namoid.ts
import { createNamoIDNextClient } from "@namoidhq/nextjs";

export const namoid = createNamoIDNextClient({
  clientId: process.env.NAMOID_CLIENT_ID!,
  clientSecret: process.env.NAMOID_CLIENT_SECRET!,
  appBaseUrl: process.env.NEXT_PUBLIC_APP_URL!,
  callbackPath: "/api/auth/callback/namoid",
  postLoginRedirectPath: "/dashboard",
  postLogoutRedirectPath: "/login",
});

NAMOID_CLIENT_ID=namoid_client_test_…
NAMOID_CLIENT_SECRET=namoid_secret_test_…
NEXT_PUBLIC_APP_URL=http://localhost:3000

Create a confidential web application in the Console and register this exact callback URL:

http://localhost:3000/api/auth/callback/namoid

Keep the Client Secret server-side. Do not prefix it with NEXT_PUBLIC_.

Login route

// app/api/auth/login/route.ts
import { namoid } from "@/lib/namoid";

export const GET = () => namoid.login();

Pass { returnTo: "/dashboard", prompt: "login" } when you need an explicit destination and a fresh authentication ceremony. returnTo must remain a relative application path.

Callback route

// app/api/auth/callback/namoid/route.ts
import { namoid } from "@/lib/namoid";

export const GET = (request: Request) =>
  namoid.callback(request, {
    async onSuccess({ tokens, identity }) {
      // Create your own opaque, HttpOnly application session here.
      // Keep NamoID tokens server-side.
      return new Response(null, {
        status: 302,
        headers: { location: "/dashboard" },
      });
    },
    async onError(error) {
      console.error(error);
      return new Response(null, {
        status: 302,
        headers: { location: "/login?error=auth" },
      });
    },
  });

The SDK validates transaction age, state, response issuer, PKCE, the signed ID token, nonce, and the UserInfo subject before calling onSuccess. Transaction cookies are HttpOnly, SameSite=Lax, and Secure on HTTPS.

Identity scopes

The SDK requests openid profile email internally and adds offline_access for this confidential flow. Customers do not configure these scopes for ordinary sign-in.

A refresh token is returned only when granted by the issuer. Store it in a protected server-side session and replace it after every successful rotation.

Refresh

const rotated = await namoid.refresh(serverSession.refreshToken);

Update the server-side session with the rotated token response.

Logout

return namoid.logout({
  refreshToken: serverSession.refreshToken,
  idTokenHint: serverSession.idToken,
});

The SDK revokes the application grant. Supplying the retained ID-token hint also redirects through the discovered end-session endpoint to clear the NamoID browser SSO session and return to the registered post-logout destination.

Clear your own application session as part of the same operation.

Options

Option	Purpose
clientId	Public application identifier
clientSecret	Confidential server credential
appBaseUrl	Absolute origin used for callbacks and safe redirects
callbackPath	Callback route; defaults to /api/auth/callback/namoid
postLoginRedirectPath	Default relative destination after sign-in
postLogoutRedirectPath	Default relative destination after logout
errorRedirectPath	Default relative destination for callback errors
cookiePrefix	Prefix for short-lived transaction cookies
transactionMaxAgeSeconds	Transaction lifetime; defaults to 10 minutes
fetcher	Optional custom fetch implementation

The SDK intentionally discovers the issuer and OAuth endpoints. Do not add an issuer, Hosted Auth URL, or application ID to configuration.

Production checklist

• Use separate Test and Live Client IDs and secrets.
• Register exact callback and post-logout URLs.
• Keep tokens in a protected server-side session.
• Rotate refresh tokens and handle revoked or expired grants by restarting sign-in.
• Clear the local application session during logout.
• Avoid logging codes, tokens, secrets, or identity claims.