workos · southgate · Mar 2, 2026 · Mar 2, 2026 · Mar 4, 2026
diff --git a/jest.config.js b/jest.config.js
@@ -0,0 +1,16 @@
+const nextJest = require('next/jest');
+
+const createJestConfig = nextJest({
+  dir: './',
+});
+
+const customJestConfig = {
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  testEnvironment: 'jest-environment-jsdom',
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
+};
+
+module.exports = createJestConfig(customJestConfig);
diff --git a/jest.setup.js b/jest.setup.js
@@ -0,0 +1 @@
+import '@testing-library/jest-dom';
diff --git a/package.json b/package.json
@@ -6,7 +6,9 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "dependencies": {
     "@workos-inc/authkit-nextjs": "0.4.2",
@@ -17,11 +19,17 @@
     "react-dom": "^18"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20",
     "@types/react": "^18",
     "@types/react-dom": "^18",
     "eslint": "^8",
     "eslint-config-next": "14.1.4",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "ts-jest": "^29.4.6",
     "typescript": "^5"
   }
 }
diff --git a/src/app/api/test-invitation-token/route.ts b/src/app/api/test-invitation-token/route.ts
@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  storeInvitationToken,
+  getStoredInvitationToken,
+  consumeInvitationToken,
+  clearInvitationToken,
+} from '@/lib/invitation-token';
+
+export async function GET(request: NextRequest) {
+  const action = request.nextUrl.searchParams.get('action');
+  const token = request.nextUrl.searchParams.get('token');
+
+  try {
+    switch (action) {
+      case 'store':
+        if (!token) {
+          return NextResponse.json({ error: 'Token required for store action' }, { status: 400 });
+        }
+        await storeInvitationToken(token);
+        return NextResponse.json({ success: true, action: 'stored', token });
+
+      case 'get':
+        const storedToken = await getStoredInvitationToken();
+        return NextResponse.json({ success: true, action: 'get', token: storedToken || null });
+
+      case 'consume':
+        const consumedToken = await consumeInvitationToken();
+        return NextResponse.json({ success: true, action: 'consumed', token: consumedToken || null });
+
+      case 'clear':
+        await clearInvitationToken();
+        return NextResponse.json({ success: true, action: 'cleared' });
+
+      default:
+        return NextResponse.json({
+          error: 'Invalid action. Use: store, get, consume, or clear',
+          usage: {
+            store: '/api/test-invitation-token?action=store&token=YOUR_TOKEN',
+            get: '/api/test-invitation-token?action=get',
+            consume: '/api/test-invitation-token?action=consume',
+            clear: '/api/test-invitation-token?action=clear',
+          },
+        }, { status: 400 });
+    }
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
@@ -1,8 +1,10 @@
 import type { Metadata } from 'next';
 import { Inter } from 'next/font/google';
+import { Suspense } from 'react';
 
 import './globals.css';
 import BackLink from './back-link';
+import { InvitationTokenCapture } from '@/components/InvitationTokenCapture';
 
 const inter = Inter({ subsets: ['latin'] });
 
@@ -15,6 +17,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en">
       <body className={inter.className}>
+        <Suspense fallback={null}>
+          <InvitationTokenCapture />
+        </Suspense>
         <BackLink />
         {children}
       </body>

diff --git a/src/app/using-hosted-authkit/basic/callback/route.ts b/src/app/using-hosted-authkit/basic/callback/route.ts
@@ -1,5 +1,6 @@
 import { WorkOS } from '@workos-inc/node';
 import { redirect } from 'next/navigation';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -16,12 +17,16 @@ const workos = new WorkOS(process.env.WORKOS_API_KEY);
 export async function GET(request: Request) {
   const code = new URL(request.url).searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   let response;
 
   try {
     response = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
   } catch (error) {
     response = error;

diff --git a/src/app/using-hosted-authkit/with-session/callback/route.ts b/src/app/using-hosted-authkit/with-session/callback/route.ts
@@ -2,6 +2,7 @@ import { WorkOS } from '@workos-inc/node';
 import { NextResponse } from 'next/server';
 import { SignJWT } from 'jose';
 import { getJwtSecretKey } from '../auth';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -15,10 +16,14 @@ export async function GET(request: Request) {
   const url = new URL(request.url);
   const code = url.searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   try {
     const { user } = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
 
     // Create a JWT with the user's information

diff --git a/src/app/using-your-own-ui/sign-in/email-password/email-password.ts b/src/app/using-your-own-ui/sign-in/email-password/email-password.ts
@@ -11,18 +11,23 @@
 // to the client for security reasons.
 
 import { WorkOS } from '@workos-inc/node';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 const workos = new WorkOS(process.env.WORKOS_API_KEY);
 
 export async function signIn(prevState: any, formData: FormData) {
   try {
+    // Check for a stored invitation token (persisted across auth flows like password reset)
+    const invitationToken = await consumeInvitationToken();
+
     // For the sake of simplicity, we directly return the user here.
     // In a real application, you would probably store the user in a token (JWT)
     // and store that token in your DB or use cookies.
     return await workos.userManagement.authenticateWithPassword({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       email: String(formData.get('email')),
       password: String(formData.get('password')),
+      invitationToken,
     });
   } catch (error) {
     return { error: JSON.parse(JSON.stringify(error)) };

diff --git a/src/app/using-your-own-ui/sign-in/github-oauth/callback/route.ts b/src/app/using-your-own-ui/sign-in/github-oauth/callback/route.ts
@@ -1,5 +1,6 @@
 import { WorkOS } from '@workos-inc/node';
 import { redirect } from 'next/navigation';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -16,12 +17,16 @@ const workos = new WorkOS(process.env.WORKOS_API_KEY);
 export async function GET(request: Request) {
   const code = new URL(request.url).searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   let response;
 
   try {
     response = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
   } catch (error) {
     response = error;

diff --git a/src/app/using-your-own-ui/sign-in/google-oauth/callback/route.ts b/src/app/using-your-own-ui/sign-in/google-oauth/callback/route.ts
@@ -1,5 +1,6 @@
 import { WorkOS } from '@workos-inc/node';
 import { redirect } from 'next/navigation';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -16,12 +17,16 @@ const workos = new WorkOS(process.env.WORKOS_API_KEY);
 export async function GET(request: Request) {
   const code = new URL(request.url).searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   let response;
 
   try {
     response = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
   } catch (error) {
     response = error;

diff --git a/src/app/using-your-own-ui/sign-in/magic-auth/magic-auth.ts b/src/app/using-your-own-ui/sign-in/magic-auth/magic-auth.ts
@@ -11,6 +11,7 @@
 // to the client for security reasons.
 
 import { WorkOS } from '@workos-inc/node';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 const workos = new WorkOS(process.env.WORKOS_API_KEY);
 
@@ -26,13 +27,17 @@ export async function sendCode(prevState: any, formData: FormData) {
 
 export async function signIn(prevState: any, formData: FormData) {
   try {
+    // Check for a stored invitation token (persisted across auth flows like password reset)
+    const invitationToken = await consumeInvitationToken();
+
     // For the sake of simplicity, we directly return the user here.
     // In a real application, you would probably store the user in a token (JWT)
     // and store that token in your DB or use cookies.
     return await workos.userManagement.authenticateWithMagicAuth({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code: String(formData.get('code')),
       email: String(formData.get('email')),
+      invitationToken,
     });
   } catch (error) {
     return { error: JSON.parse(JSON.stringify(error)) };

diff --git a/src/app/using-your-own-ui/sign-in/microsoft-oauth/callback/route.ts b/src/app/using-your-own-ui/sign-in/microsoft-oauth/callback/route.ts
@@ -1,5 +1,6 @@
 import { WorkOS } from '@workos-inc/node';
 import { redirect } from 'next/navigation';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -16,12 +17,16 @@ const workos = new WorkOS(process.env.WORKOS_API_KEY);
 export async function GET(request: Request) {
   const code = new URL(request.url).searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   let response;
 
   try {
     response = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
   } catch (error) {
     response = error;

diff --git a/src/app/using-your-own-ui/sign-in/sso/callback/route.ts b/src/app/using-your-own-ui/sign-in/sso/callback/route.ts
@@ -1,5 +1,6 @@
 import { WorkOS } from '@workos-inc/node';
 import { redirect } from 'next/navigation';
+import { consumeInvitationToken } from '@/lib/invitation-token';
 
 // This is a Next.js Route Handler.
 //
@@ -16,12 +17,16 @@ const workos = new WorkOS(process.env.WORKOS_API_KEY);
 export async function GET(request: Request) {
   const code = new URL(request.url).searchParams.get('code') || '';
 
+  // Check for a stored invitation token (persisted across auth flows like password reset)
+  const invitationToken = await consumeInvitationToken();
+
   let response;
 
   try {
     response = await workos.userManagement.authenticateWithCode({
       clientId: process.env.WORKOS_CLIENT_ID || '',
       code,
+      invitationToken,
     });
   } catch (error) {
     response = error;

diff --git a/src/components/InvitationTokenCapture.tsx b/src/components/InvitationTokenCapture.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { storeInvitationToken } from '@/lib/invitation-token';
+
+/**
+ * Client component that captures invitation_token from URL parameters
+ * and stores it in a cookie for persistence across auth flows.
+ * 
+ * This ensures that if a user:
+ * 1. Receives an invitation
+ * 2. Clicks to accept but forgets their password
+ * 3. Resets their password
+ * 
+ * The invitation token will still be available after password reset
+ * to complete the invitation acceptance.
+ */
+export function InvitationTokenCapture() {
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    const invitationToken = searchParams.get('invitation_token');
+    if (invitationToken) {
+      storeInvitationToken(invitationToken);
+    }
+  }, [searchParams]);
+
+  return null;
+}