Add Login to Next.js Without an Account

Add hosted WorkOS login and protected routes to a Next.js app.

Introduction

30 Second Summary

Adding login often starts with creating accounts and copying secret values between screens. That setup can delay the first successful sign-in.

In this project, you will add authentication to a fresh Next.js app with WorkOS AuthKit. You will see a complete login flow before claiming its temporary WorkOS environment.

What You'll Build

Your finished app takes you through a hosted login page before returning to a home page that shows your user details.

By the end of this project, you'll have:

A working sign-in flow that opens a hosted login page and returns you to your app.
A signed-in home page that displays your user details and gives you a working Sign out control.
A protected page that sends signed-out visitors to the login page.
Secret Mission: An optional challenge that extends your app's authentication flow.

Are there any prerequisites?

You'll need Node.js and Git installed before you begin. You do not need a WorkOS account or any API keys to get started.

Before We Start

Your Next.js app will rely on WorkOS AuthKit for sign-in. The installation flow needs a dependable local workspace.

You will prepare Node.js with npm. You will also prepare Git for the first project commit.

A terminal gives you a place to run commands. Your code editor holds the app files. Your browser displays the local app during testing.

In this step, get ready to:

Install Node.js with npm.
Prepare Git for clean commits.
Confirm your terminal, code editor, and browser are available.

Check Node.js and npm

Node.js runs the development tools behind your app. Version 20.9 or higher supports the current Next.js setup.

The Node.js installer includes npm. You use that command to download the project packages.

Press Cmd+Space on macOS or the Windows key on Windows to open your search bar.
Type Terminal on macOS or PowerShell on Windows into the search bar.
Press Enter to open the terminal.
Check your Node.js and npm versions by running these commands:

node --version
npm --version

What do these checks prove?

The first command prints your Node.js version. The second command confirms that npm was installed with it.

Two version numbers mean both commands are available from your terminal.

✔️ I see version 20.9 or higher

Your Node.js version meets the requirement. Your printed npm version confirms that the package manager is ready.

Good start. The runtime behind your Next.js app is ready to build the project.

ⓧ I see an older version

Your current Node.js version needs an upgrade before you create the app.

Visit the official Node.js download page.
Download the latest LTS installer for your operating system.

Your computer may ask for permission to make changes. This is expected from the installer you downloaded.

Run the Node.js installer.
Follow the installer prompts.
Close your terminal after the installation finishes.
Reopen your terminal through the operating system search bar.
Check the updated versions by running these commands:

node --version
npm --version

What should you see?

You should see Node.js version 20.9 or higher. A second version number confirms that npm is installed.

ⓧ Command not found

Your terminal cannot find Node.js yet. Installing the LTS release adds both Node.js and npm.

Visit the official Node.js download page.
Download the latest LTS installer for your operating system.

Your computer may ask for permission to make changes. This is expected from the installer you downloaded.

Run the Node.js installer.
Follow the installer prompts.
Close your terminal after the installation finishes.
Reopen your terminal through the operating system search bar.
Confirm the installation by running these commands:

node --version
npm --version

What should you see?

You should see a Node.js version followed by an npm version. Node.js must show version 20.9 or higher.

Node.js check still failing?

Close every terminal window after installation. A newly opened terminal can detect the updated commands.

Still stuck? Help me troubleshoot my Node.js and npm installation.

Prepare Git for commits

The next step creates a project commit before the authentication installer runs. Git needs to be installed before it can record that clean starting point.

Check whether Git is installed by running this command:

git --version

What does this check prove?

This command asks Git to print its installed version. A version number confirms that your terminal can reach Git.

✔️ I see a Git version

Git is installed. You can now check the identity it uses for commits.

ⓧ Command not found

Git needs to be installed before you can create the project commit.

Visit the official Git installation page.
Select your operating system.
Follow the installation instructions for your platform.
Close your terminal after the installation finishes.
Reopen your terminal through the operating system search bar.
Confirm the installation by running this command:

git --version

What should you see?

You should see a line containing the installed Git version. That output confirms Git is available to your terminal.

Every Git commit records an author name and email address. A global identity supplies those details to new projects on this computer.

Check your global Git name and email by running these commands:

git config --global --get user.name
git config --global --get user.email

What do these checks show?

The first line prints the author name Git places on your commits. The second line prints the corresponding email address.

Blank output means that value still needs to be configured.

✔️ I see my name and email

Your Git identity is already configured. Future commits can record you as their author.

ⓧ One or both values are blank

Git needs both values before you make the first commit. You only need to set this global identity once on this computer.

Open the official first-time Git setup guide.
Follow the identity instructions using your own name.
Use an email address you want attached to your commits.
Return to your terminal.
Verify the saved identity by running these commands:

git config --global --get user.name
git config --global --get user.email

What should you see?

You should see your chosen name on the first line. You should see your chosen email address on the second line.

Git setup still incomplete?

Make sure you completed both identity commands from the official guide. Each check stays blank until its matching value is saved.

Need a hand? Help me configure my Git commit identity.

Confirm your editor and browser

The code editor is where you change the app. The browser shows each local result during testing.

Press Cmd+Space on macOS or the Windows key on Windows to open your search bar.
Type the name of your installed code editor into the search bar.
Press Enter to launch the editor.

You should see the editor window load with an option to create or open a file.

Return to the operating system search bar.
Type the name of your browser into the search bar.
Press Enter to launch the browser.
Confirm your browser can reach WorkOS by opening the WorkOS website.

You should see the WorkOS website load. This confirms that the browser you use for login and dashboard confirmation is available.

Before you run the final check, which three tools do you expect to print a version number?

Verify your command-line workspace by running these commands:

node --version
npm --version
git --version

What should you see?

You should see three version lines. The Node.js line must show version 20.9 or higher.

Those results confirm that Node.js, npm, and Git are ready for the project.

That is your development foundation in place. Next, you will create the Next.js app and run its default page locally.

Create a Next.js App

Your login flow needs a working app before authentication can be added. A clean Git history also gives the installer a reliable starting point.

This step creates a fresh Next.js app with version 15.3 or later.

You will record the generated files in an initial commit. The default page on localhost proves the app can run before you add login.

In this step, get ready to:

Create a fresh app with a supported Next.js version.
Commit the generated app with a clean Git working tree.
Run the app locally and view the default page.

Create the app on your Desktop

The create-next-app tool generates the project structure and installs the packages Next.js needs. Starting from your Desktop keeps the new my-app folder easy to find.

Press Cmd+Space on macOS or the Windows key on Windows to open your search bar.
Type Terminal on macOS or PowerShell on Windows to find your terminal.
Press Enter to open the terminal.

Your operating system uses its own syntax to reach the Desktop folder.

macOS

Move to your Desktop by running this command:

cd ~/Desktop

What does this command do?

The cd command changes your current folder. The ~ shortcut represents your home folder.

Windows

Move to your Desktop in PowerShell by running this command:

Set-Location -Path $HOME\Desktop

What does this command do?

The Set-Location command changes your current folder. The $HOME value points to your Windows home folder.

The scaffold downloads project dependencies. It may take a few minutes while your terminal prints progress.

Create the fresh Next.js app by running this command:
Approve the download if npm asks for permission to install create-next-app.

npx create-next-app@latest my-app --yes

What does this command do?

The create-next-app tool creates the my-app folder with a fresh Next.js project.
The --yes option accepts the recommended defaults without opening a setup wizard.
The installer downloads the project dependencies so the app can run locally.

Your fresh app is now scaffolded inside my-app. The project dependencies are ready to use.

App creation failed?

Check whether a folder named my-app already exists on your Desktop.
Confirm your internet connection works because the scaffold downloads packages.

Still stuck? Help me troubleshoot the failed Next.js scaffold.

Prove the app is installer-ready

The authentication installer expects Next.js version 15.3 or later. Checking the installed version confirms that your scaffold meets this requirement.

Move into the generated my-app folder by running this command:

cd my-app

Why change folders?

Your project commands need to run from inside my-app. This folder contains the app and its installed packages.

Check the installed Next.js version by running this command:

npx next --version

What does this check?

The command reads the Next.js package installed inside my-app. Its output gives you the exact version used by this project.

✔️ I see version 15.3 or higher

Your Next.js version meets the project requirement. You can prepare the Git baseline.

ⓧ I see an older version

Update the framework packages before creating your initial commit.

Install the latest framework packages by running this command:

npm i next@latest react@latest react-dom@latest

What does this update?

This updates Next.js and its React dependencies together. Your package files record the new versions.

Check the installed Next.js version again by running this command:

npx next --version

What should you confirm?

The new output should show Next.js version 15.3 or higher. That confirms the update succeeded.

ⓧ Command not found

The project is missing its local Next.js package. Installing the framework packages restores the command.

Install the required framework packages by running this command:

npm i next@latest react@latest react-dom@latest

What does this install?

This adds Next.js and its React dependencies to the project. It also updates the package files used by npm.

Check the installed Next.js version by running this command:

npx next --version

What should you confirm?

The output should now show Next.js version 15.3 or higher. The local framework command is ready.

A clean working tree gives the next installer an exact baseline. Any files it adds can then be identified through Git.

Inspect the current Git state by running this command:

git status

What does this check?

Git compares the project files with the latest commit. The output tells you whether the scaffold is already committed or still has changes to record.

✔️ The working tree is clean

Your scaffold already created the initial commit. The repository is ready for the next step.

ⓧ Git lists changes

The generated files still need to be recorded as the project baseline.

Stage the generated files and create the initial commit by running these commands:

git add .
git commit -m "Initial commit"

What do these commands do?

The git add . command stages every generated file in the app.
The git commit -m "Initial commit" command records those staged files as the starting snapshot.

Confirm the repository is clean by running this command:

git status

What should you see?

Git should report nothing to commit, working tree clean. This proves every generated file belongs to the initial commit.

That baseline is ready. Changes introduced by the authentication installer will now stand out clearly.

Run the app locally

A development server turns the generated files into a page your browser can load. This final check proves the scaffold works before authentication changes it.

Before you start the server, what do you expect to see when you open the local address?

Start the development server by running this command:

npm run dev

What happens when the server starts?

Next.js compiles the starter page and keeps the command running. The first startup may take about a minute.

Keep this terminal running while you use the app. Press Ctrl+C when you want to stop the server.

Select the address bar in your browser.
Enter http://localhost:3000 to load the app.

You should see the default Next.js starter page. This confirms the development server successfully served your app on localhost.

Default page not loading?

Check that the terminal running the server remains open.
Confirm the terminal is inside the my-app folder.
Check whether the terminal reports a different local address because another process uses the default port.

Need help? Help me troubleshoot the local Next.js page.

You now have a live Next.js starting point with a committed Git baseline. The app is ready for authentication changes.

Your clean app is running locally. Next up, you will let the authentication installer add the environment and route files.

Install WorkOS AuthKit

You already have a clean Next.js app serving its default page. That clean starting point gives the installer a safe baseline for its edits.

Now you will use WorkOS AuthKit to add the foundations for sign-in and sessions. Its installer creates a temporary environment without requiring a WorkOS account or your own API keys.

In this step, get ready to:

Run the WorkOS installer to create a temporary environment.
Review the generated settings in .env.local without exposing their values.
Inspect the generated callback route and proxy with git diff.

Run the WorkOS installer

An unclaimed environment gives your app working credentials before you own a WorkOS account. The WorkOS CLI connects that environment to the app.

The first run may pause for npm to download the CLI package. Expect the installer to take about two minutes while it configures the project.

Switch back to the terminal from the previous step.
Stop the development server with Ctrl+C if it is still running.

Before you run the installer, which parts of the app do you think one authentication command needs to change?

Be ready to approve a package download if npm asks for permission.
Install AuthKit into the Next.js app by running this command:

npx workos@latest install

What does the installer do?

It provisions a temporary WorkOS environment for the app.
It writes the generated configuration to .env.local.
It installs @workos-inc/authkit-nextjs.
It updates package.json with the AuthKit dependency.
It updates package-lock.json with the resolved packages.
It generates the callback route and proxy integration.

Wait for the installer to finish.
Read the installer summary before leaving the terminal.

You should see that a temporary environment was created. The summary should also report the AuthKit integration changes.

That is the biggest setup leap done. Your app now has AuthKit's session foundation.

Installer stopped early?

Return to the clean commit from the previous step if the installer reports unrelated uncommitted changes.
Check that the terminal is still inside the Next.js app folder if framework detection fails.
Retry the installer after restoring your network connection if provisioning stops.

Still blocked? Help me troubleshoot the WorkOS AuthKit installer.

Review the generated environment settings

The .env.local file connects your app to its temporary WorkOS environment. It also contains credentials that must remain private.

Keep these credentials private

Opening .env.local in your editor is safe. Keep its values out of screenshots.

Never paste the file's values into chat. The file must remain outside Git.

Switch back to the code editor from earlier.
Select .env.local from the app's file sidebar.
Confirm that WORKOS_API_KEY appears.
Confirm that WORKOS_CLIENT_ID appears.
Confirm that WORKOS_CLAIM_TOKEN appears.
Confirm that WORKOS_COOKIE_PASSWORD appears.
Confirm that NEXT_PUBLIC_WORKOS_REDIRECT_URI appears.
Close .env.local without changing its values.

What do these settings control?

The WORKOS_API_KEY authenticates server-side WorkOS requests.
The WORKOS_CLIENT_ID identifies the temporary environment used by your app.
The WORKOS_CLAIM_TOKEN lets you claim that environment later.
The WORKOS_COOKIE_PASSWORD protects the application's session cookies.
The NEXT_PUBLIC_WORKOS_REDIRECT_URI tells AuthKit where to return after hosted login.

Good. You have confirmed that the app received every setting needed for the temporary environment.

Inspect the generated Git changes

A Git diff gives you an audit trail of the installer's edits. It lets you review generated authentication code before committing it.

Return to the terminal from earlier.

Before you check the diff, which files do you expect the installer to have changed?

Review the installer changes by running this command:

git diff

What should the diff show?

Changes to package.json show the new AuthKit dependency.
Changes to package-lock.json record the installed package versions.
The generated app/callback/route.ts completes the hosted login redirect.
The generated proxy.ts integrates session handling and route protection.
The credential values from .env.local should stay outside the diff.

Switch back to the code editor from earlier.
Select app/callback/route.ts from the file sidebar.
Read the callback route to identify where the hosted login redirect completes.
Select proxy.ts from the file sidebar.
Read the proxy to identify where session handling is connected to Next.js.
Leave the installer changes uncommitted so the diff remains available for review.

You should find a callback route that establishes the application session after login. You should also find a proxy that connects WorkOS session handling to the app.

Diff looks empty?

Check that the terminal is inside the same Next.js app where you ran the installer.
Confirm that the installer reached its completion summary.
Check the file sidebar for app/callback/route.ts and proxy.ts.

Need another pair of eyes? Help me find the WorkOS installer changes.

Your temporary WorkOS environment is connected to the app. Next up, you will add the controls that let someone sign in or sign out.

Add Login Controls

The installer has now wired WorkOS AuthKit into your Next.js app.

Your home page still needs to respond to the current session. You’ll add controls that switch between signed-out and signed-in states.

In this step, get ready to:

Read the current session on the home page.
Render the correct login control for each session state.
Start the development server and verify the signed-out view.

Connect the home page to the session

A Server Component can call withAuth() before the page reaches the browser. A Server Action keeps each authentication request on the server.

Open app/page.tsx from your code editor’s file explorer.
Replace the file’s contents by copying the code below:

import { getSignInUrl, signOut, withAuth } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export default async function HomePage() {
  // Read the server-side session before choosing which controls to show.
  const { user } = await withAuth();
  // Give signed-out visitors a server-side sign-in action.
  if (!user) {
    return (
      <main>
        <h1>Welcome</h1>
        <p>Please sign in to continue.</p>
        <form action={async () => { 'use server'; redirect(await getSignInUrl()); }}>
          <button type="submit">Sign in</button>
        </form>
      </main>
    );
  }
  // Show session details and a server-side sign-out action.
  return (
    <main>
      <h1>Welcome back{user.firstName && `, ${user.firstName}`}</h1>
      <p>Email: {user.email}</p>
      <form action={async () => { 'use server'; await signOut(); }}>
        <button type="submit">Sign out</button>
      </form>
    </main>
  );
}

What does this code do?

The user value holds the current user when a session exists.
The getSignInUrl() helper creates the hosted login destination after the visitor submits the sign-in form.
The signOut() helper ends the current session after the visitor submits the sign-out form.
The conditional rendering sends only the matching session view to the browser.

Save app/page.tsx.

✔️ Awesome, I've got everything!

Your file now contains the complete session-aware home page.

ⓧ I'd like to double check the full code

import { getSignInUrl, signOut, withAuth } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export default async function HomePage() {
  // Read the server-side session before choosing which controls to show.
  const { user } = await withAuth();
  // Give signed-out visitors a server-side sign-in action.
  if (!user) {
    return (
      <main>
        <h1>Welcome</h1>
        <p>Please sign in to continue.</p>
        <form action={async () => { 'use server'; redirect(await getSignInUrl()); }}>
          <button type="submit">Sign in</button>
        </form>
      </main>
    );
  }
  // Show session details and a server-side sign-out action.
  return (
    <main>
      <h1>Welcome back{user.firstName && `, ${user.firstName}`}</h1>
      <p>Email: {user.email}</p>
      <form action={async () => { 'use server'; await signOut(); }}>
        <button type="submit">Sign out</button>
      </form>
    </main>
  );
}

Start the app and check the signed-out view

The development server compiles your updated home page. It also keeps watching for saved changes.

Before you run the app, do you expect the home page to show both controls or only the control that matches the current session?

Return to the terminal from earlier.
Start the development server by running this command:

npm run dev

What does this command do?

The development server compiles the updated home page.

It keeps running so your browser can request the app from localhost.

You should see terminal output showing that the app is ready with a local address.

Return to the localhost browser tab from earlier.
Refresh the page at http://localhost:3000.

You should see a Sign in button on the home page. That button proves your signed-out session path works.

Don't see the Sign in button?

Save app/page.tsx if your editor still shows unsaved changes.
Confirm .env.local remains beside package.json.
Read the terminal’s latest compilation message for the affected line in app/page.tsx.

Still stuck? Help me troubleshoot why my WorkOS Sign in button is missing from my Next.js home page.

Your home page now reacts to session state. Next, you’ll use the Sign in button to complete the hosted login flow.

Sign In with a Test User

Your Next.js app now shows a working Sign in control. The next goal is to prove that it can authenticate a real test user.

WorkOS AuthKit handles the login on a hosted page. Its callback route establishes a browser session that lets the home page identify the signed-in user.

In this step, get ready to:

Open the hosted login page from your app.
Complete the hosted login as a test user.
Confirm the home page shows your signed-in details.

Open the hosted login page

The Sign in control sends your browser to the hosted AuthKit page for your temporary environment. WorkOS manages the authentication flow there.

Switch back to the browser tab showing http://localhost:3000.
Confirm the home page still shows the Sign in control.
Click Sign in.

You'll see the hosted AuthKit page for your temporary WorkOS environment.

Hosted Login Page Didn't Load?

Return to the terminal panel from earlier if the browser stays on your home page.
Check that the Next.js development server is still running.
Refresh http://localhost:3000 before clicking Sign in again.

Still stuck? Help me troubleshoot why the hosted AuthKit login page does not open.

Create your test user

The temporary environment can authenticate users before you claim it. A test user lets you verify the full login flow without creating a WorkOS account.

Follow the hosted page's prompts to create your test user.
Complete each identity check requested for that test user.

Before you complete the last prompt, where do you think WorkOS sends your browser after authentication succeeds?

Complete the final hosted login prompt.

WorkOS sends your browser back to the app through the installer-generated callback route.

How Does the Callback Finish Sign-In?

The app/callback/route.ts route receives the result from the hosted login flow. It establishes the application session before returning you to the home page.

Verify the active session

Before you inspect the home page closely, what should change now that the callback has created an active session?

Check the home page for your test user's details.
Confirm the Sign out control appears in place of Sign in.

That is the complete login round trip working. Your temporary WorkOS environment now recognizes the test user through an active browser session.

Still Seeing Sign In?

Refresh the home page once after the hosted login returns you to localhost.
Check the development server terminal for a callback-related error.
Repeat the hosted login flow if the previous attempt did not finish.

Need another pair of eyes? Help me find out why my test user returned without an active session.

Your test user now has an active session. Next, you'll sign out before testing a page that requires authentication.

Protect a Session-Only Page

Your WorkOS AuthKit login now creates a real browser session. Your home page can read that session to display the test user.

Some pages need stronger access control. You will add a page that requires a session. You will then sign out to prove that a visitor without a session gets redirected to hosted login.

In this step, get ready to:

Create a page that requires an active WorkOS AuthKit session.
Sign out of the test-user session.
Verify that the protected page redirects you to hosted login.

Create the protected page

The withAuth() session helper can require a signed-in user before a server component renders. The ensureSignedIn option sends visitors without a session to AuthKit automatically.

Create app/protected/page.tsx using the file controls in your editor sidebar.
Add the protected page by copying this code into app/protected/page.tsx:

import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function ProtectedPage() {
  // If the user isn't signed in, they will be automatically redirected to AuthKit
  const { user } = await withAuth({ ensureSignedIn: true });

  return <p>Welcome back{user.firstName && `, ${user.firstName}`}</p>;
}

What does this code do?

The withAuth() helper reads the session managed by AuthKit.
The ensureSignedIn: true option makes a valid session mandatory for this page.
The user value supplies the first name used in the protected greeting.

Save app/protected/page.tsx.
Return to the browser from earlier.
Enter http://localhost:3000/protected in the address bar.

You should see Welcome back followed by the test user's first name. This confirms that the page can read your active session.

Protected page not loading?

Confirm that the file path is exactly app/protected/page.tsx.
Confirm that the development server from earlier is still running.
Compare the import path with the code above if your browser shows a module error.

Still stuck? Help me troubleshoot my protected AuthKit page.

✔️ Awesome, I've got everything!

Your protected page is saved. Its personalized greeting confirms that the active session passed the access check.

ⓧ I'd like to double check the full code

import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function ProtectedPage() {
  // If the user isn't signed in, they will be automatically redirected to AuthKit
  const { user } = await withAuth({ ensureSignedIn: true });

  return <p>Welcome back{user.firstName && `, ${user.firstName}`}</p>;
}

Sign out of the test session

Your current session allows the protected page to render. Signing out creates the exact state needed to test how the page treats an unauthenticated visitor.

Return to http://localhost:3000 using the browser address bar.
Click Sign out on the home page.

You should return to the signed-out home page. You should see the Sign in control again.

Still seeing your user details?

Refresh the home page to load the latest session state.
Confirm that you clicked the existing Sign out control from the home page.

Need another pair of eyes? Help me check why my WorkOS session remains active.

Test access without a session

Before you check, predict whether the protected greeting or the hosted login page will appear without an active session.

Enter http://localhost:3000/protected in the browser address bar.

You should be redirected away from the protected page to the WorkOS hosted login page. The protected greeting does not render because the browser no longer has a valid session.

You have proved that the access gate works. Your session-only page now sends signed-out visitors through authentication before revealing its content.

Still seeing the protected greeting?

Confirm that the home page showed the Sign in control before you revisited the protected URL.
Refresh http://localhost:3000/protected to force a new request after signing out.
Compare app/protected/page.tsx with the full-code tab above.

If the protected content remains visible, help me diagnose the session check.

Your app now protects content with a real session check. Next, you will claim the temporary environment so it stays under your control.

Claim Your WorkOS Environment

Your protected route in Next.js already proves that session checks work. Signed-out visitors now reach the hosted login page through WorkOS AuthKit.

The environment behind that flow remains temporary. Claiming it before its 7-day expiry places it in your WorkOS dashboard.

In this step, get ready to:

Start the ownership handoff with the WorkOS CLI.
Confirm the environment claim in your browser.
Verify the claimed environment retains its test user.

Start the ownership handoff

A claim links the installer-created environment to the WorkOS account you confirm in the browser. The existing authentication setup stays attached to that environment.

Before you run this, predict whether the browser confirmation will keep the temporary environment or create a separate one.

Return to the terminal tab in your Next.js app folder from earlier.
Start the browser confirmation flow by running this command:

npx workos@latest profile claim

What Does This Command Do?

The profile claim command starts the ownership handoff for the installer-created temporary environment.
The .env.local file provides the WORKOS_CLAIM_TOKEN that identifies the temporary environment.
The browser confirmation attaches the environment to your WorkOS account.

Continue in the WorkOS browser page that the CLI opens or links.
Complete the account access prompts shown on the page.
Confirm the environment claim within 5 minutes.
Return to the terminal after the browser confirms ownership.

You'll see the browser confirm that the environment is associated with your account. The claim process then completes in the terminal.

Claim Not Completing?

Check that the terminal is in your Next.js app folder containing .env.local.
Rerun the claim command above if the browser confirmation expires.

If the handoff still does not complete, help me finish the WorkOS environment claim.

Verify the claimed environment

Claiming preserves the environment's existing content while transferring its ownership. The test user from your hosted login should remain in the environment.

Your .env.local file still contains generated credentials plus WORKOS_CLAIM_TOKEN.

Keep .env.local out of Git.

Before you check, predict whether the test user from hosted login will still be present after the claim.

Return to the WorkOS dashboard opened during the claim.
Use the environment selector to open the environment you just claimed.
Open the user list for the claimed environment.

You'll see the claimed environment in your WorkOS dashboard. The test user from your hosted login appears in that environment's user list.

That handoff is complete. Your working login setup now belongs to an environment you can return to.

Secret mission

Test Session Isolation Across Browser Windows

Your protected page blocks signed-out visitors. Now test whether a signed-in browser can accidentally share its access with a separate private window. Finish by restoring the app to its original signed-out state.

Clean Up Your Resources

Your local Next.js server and project files do not create ongoing cloud costs. Pricing for claimed WorkOS environments was not established in this project.

Resources you used:

The local development server that serves your app at http://localhost:3000.
The local Next.js app folder containing your source files and installed packages.
The untracked .env.local file containing your generated WorkOS configuration.

Your claimed WorkOS environment and test user remain in the WorkOS dashboard. This project does not include a verified deletion path for those dashboard resources.

Keep everything running

No project files or dashboard resources need to be deleted. Choose this option if you want to keep testing your login flow.

Authenticate the WorkOS CLI for your claimed environment by running:

npx workos@latest auth login

Why Remove the Claim Token?

Authenticating the WorkOS CLI connects it to the environment you claimed. The WORKOS_CLAIM_TOKEN value has finished its job and should no longer stay in .env.local.

Return to .env.local in your code editor.
Delete the entire line that starts with WORKOS_CLAIM_TOKEN.
Save .env.local.
Return to the Git diff from earlier.
Confirm that .env.local does not appear in the changes that Git can commit.
Leave the development server running while you continue testing the app.
Keep the claimed WorkOS environment and test user for future login tests.

Your app remains available at http://localhost:3000 with its claimed environment configuration.

Pause - I'll come back to this later

This option stops the local development server while preserving your app files and claimed environment.

Authenticate the WorkOS CLI for your claimed environment by running:

npx workos@latest auth login

Why Remove the Claim Token?

Authenticating the WorkOS CLI connects it to the environment you claimed. The WORKOS_CLAIM_TOKEN value has finished its job and should no longer stay in .env.local.

Return to .env.local in your code editor.
Delete the entire line that starts with WORKOS_CLAIM_TOKEN.
Save .env.local.
Return to the terminal running the Next.js development server.
Press Ctrl+C to stop the server.
Refresh http://localhost:3000 in your browser.

The local page stops loading because the development server is no longer running.

Keep the Next.js app folder in its current location.
Leave the claimed WorkOS environment and test user unchanged in the dashboard.

Your code and configuration stay ready for the next time you start the development server.

Delete - I don't want to use this again

This option removes the local Next.js app and its generated configuration from your machine.

Authenticate the WorkOS CLI for your claimed environment by running:

npx workos@latest auth login

Why Remove the Claim Token?

Authenticating the WorkOS CLI connects it to the environment you claimed. The WORKOS_CLAIM_TOKEN value has finished its job and should no longer stay in .env.local.

Return to .env.local in your code editor.
Delete the entire line that starts with WORKOS_CLAIM_TOKEN.
Save .env.local.
Return to the terminal running the Next.js development server.
Press Ctrl+C to stop the server.

The local server is now stopped. You can remove the app folder without leaving its process running.

Use your operating system's file manager to locate the Next.js app folder that contains package.json.
Delete the entire Next.js app folder using your operating system's standard delete action.
Confirm that the folder no longer appears in its previous location.

Deleting the local folder removes .env.local and the app source files. It does not delete the claimed environment or test user from the WorkOS dashboard.

Nice Work!

You did it! Your Next.js app now uses WorkOS AuthKit for working authentication.

You've learned how to:

Took an accountless WorkOS environment from automatic setup to a claimed environment in your own dashboard.
Completed the hosted login flow. You returned through the callback route with an active session that displays your test user's details.
Protected a page with session checks. You proved the protection works by opening the page while signed out and reaching the hosted login page.
Completed the optional Secret Mission to push your authentication skills further.

Ready to quiz yourself?