Skip to main content
AuthKitProvider is a client-side React component that wraps your application and provides authentication context to all child components. It manages user state, session data, and provides methods for authentication operations.

​
Usage

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AuthKitProvider>
          {children}
        </AuthKitProvider>
      </body>
    </html>
  );
}

​
Props

​
children
ReactNode
required
The child components that will have access to the authentication context.
​
onSessionExpired
false | (() => void)
Customize what happens when a session expires. By default, the entire page will be reloaded. Pass false to disable expired session checks.
<AuthKitProvider
  onSessionExpired={() => {
    // Custom handling
    console.log('Session expired');
    window.location.href = '/login';
  }}
>
  {children}
</AuthKitProvider>
​
initialAuth
Omit<UserInfo | NoUserInfo, 'accessToken'>
Initial auth data from the server. If provided, the provider will skip the initial client-side fetch, improving performance and reducing loading states.
import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function RootLayout({ children }) {
  const { user, sessionId, organizationId } = await withAuth();

  return (
    <html lang="en">
      <body>
        <AuthKitProvider initialAuth={{ user, sessionId, organizationId }}>
          {children}
        </AuthKitProvider>
      </body>
    </html>
  );
}

​
Context value

The provider exposes the following values through the useAuth hook:
​
user
User | null
The authenticated user object, or null if not authenticated.
​
sessionId
string | undefined
The current session ID.
​
organizationId
string | undefined
The ID of the organization the user is currently in.
​
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 for the user.
​
featureFlags
string[] | undefined
Array of feature flags enabled for the user.
​
impersonator
Impersonator | undefined
Information about the admin impersonating this user, if applicable.
​
loading
boolean
Indicates whether authentication data is being loaded.
​
getAuth
(options?: { ensureSignedIn?: boolean }) => Promise<void>
Fetches the latest authentication state from the server.
​
refreshAuth
(options?: { ensureSignedIn?: boolean; organizationId?: string }) => Promise<void | { error: string }>
Refreshes the authentication session, optionally switching to a different organization.
​
signOut
(options?: { returnTo?: string }) => Promise<void>
Signs out the current user and optionally redirects to a specific URL.
​
switchToOrganization
(organizationId: string, options?: SwitchToOrganizationOptions) => Promise<Omit<UserInfo, 'accessToken'> | { error: string }>
Switches the user’s active organization.

​
Session expiration handling

The provider automatically monitors session validity when the browser tab becomes visible or gains focus. If a session has expired, it will:
  1. Call the onSessionExpired callback if provided
  2. Otherwise, reload the page (default behavior)
  3. Do nothing if onSessionExpired={false}
This ensures users are redirected to sign in when their session expires in another tab.

​
Best practices

Use initialAuth for better performance

Pass server-side authentication data to initialAuth to avoid an extra client-side fetch on page load.

Disable session checks cautiously

Only set onSessionExpired={false} if you have custom session management. The default behavior protects against stale sessions.

useAuth

Access the authentication context

useAccessToken

Get the user’s access token

Build docs developers (and LLMs) love

Get started for freeTalk to us