Adding user authentication to a Next.js app with Whop OAuth

I wrote a tutorial on adding user authentication to an existing Next.js app using Whop OAuth. The TL;DR: drop Sign in with Whop into any Next.js app, skip credential storage, password hashing, email verification, and reset flows. Whop handles those.

Demo: https://nextjs-whop-oauth-demo.vercel.app/

The full integration is a few files: a couple of new modules under lib/, three route handlers under app/api/auth/, and a proxy.ts at the project root. The flow is OAuth 2.0 + PKCE; the session lives in an encrypted httpOnly cookie via iron-session. Here is how it comes together.

What you set up first

Two packages: iron-session for the encrypted session cookie, zod for env and response validation.

npm install iron-session zod

Five env vars: WHOP_CLIENT_ID, WHOP_CLIENT_SECRET, WHOP_SANDBOX, SESSION_SECRET (32+ chars; openssl rand -base64 32 does it), and NEXT_PUBLIC_APP_URL. Plus a Whop app from Sandbox.Whop.com with two redirect URIs (one for localhost, one for production), the openid, profile, and email scopes selected, and the oauth:token_exchange permission added on the Permissions tab.

Env validation with zod

I validate everything at first call (not at import time) so next build does not fail in environments where runtime env vars are not present:

import { z } from "zod";

const envSchema = z.object({
  WHOP_CLIENT_ID: z.string().startsWith("app_"),
  WHOP_CLIENT_SECRET: z.string().min(1),
  WHOP_SANDBOX: z.string().optional().transform((v) => v === "true"),
  SESSION_SECRET: z.string().min(32),
  NEXT_PUBLIC_APP_URL: z.string().url(),
});

let cached: z.infer<typeof envSchema> | null = null;

export function getEnv() {
  if (cached) return cached;
  cached = envSchema.parse({
    WHOP_CLIENT_ID: process.env.WHOP_CLIENT_ID,
    WHOP_CLIENT_SECRET: process.env.WHOP_CLIENT_SECRET,
    WHOP_SANDBOX: process.env.WHOP_SANDBOX,
    SESSION_SECRET: process.env.SESSION_SECRET,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  });
  return cached;
}

getEnv() parses once, caches the result, and gives every route handler a single typed source of truth.

The auth flow, end to end

Six things happen between the click and the dashboard render:

The user clicks the link to /api/auth/login.
The login route generates a PKCE verifier, a random state, and a random nonce, stores all three in a short lived httpOnly cookie, and redirects to https://api.whop.com/oauth/authorize?... (or the sandbox base when WHOP_SANDBOX=true).
Whop shows the consent screen and redirects to /api/auth/callback?code=...&state=....
The callback route reads the PKCE cookie, verifies the returned state matches, and POSTs to /oauth/token with the code, code_verifier, and client_secret.
The route checks that the id_token echoes the nonce, then uses the returned access_token to call /oauth/userinfo and read the user profile.
The route writes the user profile and tokens into an iron-session cookie, clears the PKCE cookie, and redirects to /dashboard.

Every step runs server side. Whop's tokens never touch the browser; the session lives in an encrypted httpOnly cookie that client side JavaScript cannot read.

The nonce gotcha

The OAuth scope requests openid, profile, and email. Adding openid turns this into an OpenID Connect flow, which means Whop requires a nonce parameter on the authorize URL. Omit it and Whop returns nonce is required before the callback ever fires.

The login route generates the nonce alongside the state and code_verifier, stashes it in the PKCE cookie, and validates it back from the id_token in the callback.

This is the single most common thing that breaks first run integrations. Worth knowing before you spend an hour reading the OAuth spec wondering what you missed.

Route protection in two layers

Protected pages check authentication in two places:

A middleware proxy (proxy.ts at the project root) matches protected routes by path and redirects unauthenticated requests to /api/auth/login.
A server side requireUser() helper reads the session inside server components and either returns the user or redirects.

Having both layers means a request that bypasses the middleware still gets caught by the component level check. And the helper makes typed user data available without each page reaching for the session manually.

Sandbox to production is one env var

The OAuth helper switches base URLs based on WHOP_SANDBOX:

function getBaseUrl(): string {
  return getEnv().WHOP_SANDBOX
    ? "https://sandbox-api.whop.com"
    : "https://api.whop.com";
}

Going to production means three things: create a production Whop app on whop.com (not the sandbox), update the env vars with the production client ID and secret, and remove WHOP_SANDBOX (or set it to false). Redirect URIs registered on the production app need to match exactly.

推荐订阅源

DEV Community