Skip to main content
withAuth is a server-side function that retrieves the authenticated user’s session information. It can be used in server components, server actions, and route handlers.

​
Usage

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

export default async function HomePage() {
  const { user } = await withAuth();
  
  if (!user) {
    return <div>Not signed in</div>;
  }
  
  return <div>Welcome back, {user.firstName}!</div>;
}

​
Signature

function withAuth(options?: { ensureSignedIn?: boolean }): Promise<UserInfo | NoUserInfo>
function withAuth(options: { ensureSignedIn: true }): Promise<UserInfo>

​
Parameters

​
options
object
Configuration options for the authentication check.

​
Returns

​
user
User | null
The authenticated user object, or null if not authenticated.
​
sessionId
string | undefined
The unique session identifier.
​
organizationId
string | undefined
The ID of the user’s current organization context.
​
role
string | undefined
The user’s role in the current organization.
​
roles
string[] | undefined
Array of all roles assigned to the user.
​
permissions
string[] | undefined
Array of permissions granted to the user.
​
entitlements
string[] | undefined
Array of entitlements available to the user.
​
featureFlags
string[] | undefined
Array of enabled feature flags for the user.
​
impersonator
Impersonator | undefined
Information about the impersonator, if the user is being impersonated.
​
accessToken
string | undefined
JWT access token for the authenticated session.

​
Examples

​
Basic usage

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

export default async function ProfilePage() {
  const { user } = await withAuth();
  
  return (
    <div>
      {user ? (
        <p>Email: {user.email}</p>
      ) : (
        <p>Please sign in</p>
      )}
    </div>
  );
}

​
Requiring authentication

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

export default async function DashboardPage() {
  // Automatically redirects to AuthKit if not signed in
  const { user } = await withAuth({ ensureSignedIn: true });
  
  return <div>Welcome to your dashboard, {user.firstName}!</div>;
}

​
Accessing feature flags

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

export default async function HomePage() {
  const { featureFlags } = await withAuth();
  
  const hasNewFeature = featureFlags?.includes('new-feature');
  
  return (
    <div>
      {hasNewFeature && <NewFeatureComponent />}
    </div>
  );
}

​
Using in a server action

'use server';

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

export async function updateProfile(formData: FormData) {
  const { user } = await withAuth({ ensureSignedIn: true });
  
  // Update user profile logic
  await database.updateUser(user.id, {
    name: formData.get('name'),
  });
}

​
Notes

  • withAuth requires the AuthKit middleware to be configured and running on the route where it’s called
  • When ensureSignedIn is true, the function will redirect unauthenticated users and never return null
  • The access token is a JWT that can be used for authentication with external services
  • Do not wrap withAuth({ ensureSignedIn: true }) in a try/catch block, as redirects in Next.js must be called outside try/catch blocks

Build docs developers (and LLMs) love

Get started for freeTalk to us