AuthKit Next.js

https://github.com/workos/authkit-nextjs
Admin
AuthKit Next.js provides helpers for authentication and session management with WorkOS & AuthKit in...
Tokens:68,653
Snippets:430
Trust Score:9.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the Next.js example with pnpm dev

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/next/README.md

Starts the Next.js development server. After running this command, navigate to http://localhost:3000 to see the example application.

```bash
pnpm dev
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/vinext/README.md

Installs the project dependencies from the repository root, as required in the Setup section.

```bash
pnpm install
```

--------------------------------

### Install with pnpm

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Install the AuthKit Next.js library and the WorkOS Node SDK as a peer dependency using pnpm.

```bash
pnpm i @workos-inc/authkit-nextjs @workos-inc/node
```

--------------------------------

### Install with Yarn

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Install the AuthKit Next.js library and the WorkOS Node SDK as a peer dependency using Yarn.

```bash
yarn add @workos-inc/authkit-nextjs @workos-inc/node
```

--------------------------------

### useAuth example with signOut

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/authkit-provider.md

Example component using useAuth with ensureSignedIn: true. It displays a loading state and a sign-out button that calls signOut with a returnTo path. The user object is available after loading completes.

```tsx
'use client';
import { useAuth } from '@workos-inc/authkit-nextjs/components';

export default function AccountButton() {
  const { user, loading, signOut } = useAuth({ ensureSignedIn: true });

  if (loading) return <div>Loading...</div>;

  return (
    <button onClick={() => signOut({ returnTo: '/' })}>
      Sign out {user.firstName}
    </button>
  );
}
```

--------------------------------

### Create .dev.vars for local wrangler development

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/vinext/README.md

Copies the example .dev.vars file to .dev.vars for local development with wrangler. Fill in your credentials.

```bash
cp .dev.vars.example .dev.vars
# Fill in your credentials
```

--------------------------------

### partitionAuthkitHeaders + applyResponseHeaders (Advanced Composition)

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware-helpers.md

Advanced composition example showing how to use partitionAuthkitHeaders and applyResponseHeaders together for rewrites.

```APIDOC
## partitionAuthkitHeaders + applyResponseHeaders (Advanced Composition)

### Description
Advanced composition example showing how to use partitionAuthkitHeaders and applyResponseHeaders together for rewrites.

### Example
```ts
import { NextRequest, NextResponse } from 'next/server';
import { authkit, partitionAuthkitHeaders, applyResponseHeaders } from '@workos-inc/authkit-nextjs';

export default async function proxy(request: NextRequest) {
  const { headers } = await authkit(request);
  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, headers);

  const response = NextResponse.rewrite(new URL('/app/dashboard', request.url), {
    request: { headers: requestHeaders },
  });
  return applyResponseHeaders(response, responseHeaders);
}
```
```

--------------------------------

### Example usage of switchToOrganization

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Example server action that calls switchToOrganization with a returnTo path and tag-based revalidation. It reads the organization ID from form data.

```ts
'use server';
import { switchToOrganization } from '@workos-inc/authkit-nextjs';

export async function switchOrg(formData: FormData) {
  const orgId = formData.get('organizationId') as string;
  await switchToOrganization(orgId, {
    returnTo: '/app',
    revalidationStrategy: 'tag',
    revalidationTags: ['dashboard-data'],
  });
}
```

--------------------------------

### signOut usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Example server action that calls signOut with a returnTo URL. The function never resolves; it always terminates via redirect() from next/navigation.

```ts
'use server';
import { signOut } from '@workos-inc/authkit-nextjs';

export async function handleSignOut() {
  await signOut({ returnTo: 'https://your-app.com/signed-out' });
}
```

--------------------------------

### Basic usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/workos.md

Shows how to import and use getWorkOS to call WorkOS SDK methods, such as listing organizations.

```typescript
import { getWorkOS } from '@workos-inc/authkit-nextjs';

const workos = getWorkOS();

// Use any WorkOS SDK method
const organizations = await workos.organizations.listOrganizations({ limit: 10 });
```

--------------------------------

### authkitMiddleware usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware.md

Example of using authkitMiddleware in middleware.ts for Next.js ≤ 15. Enables debug mode and matches routes '/' and '/admin'.

```typescript
// middleware.ts (Next.js ≤ 15)
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';

export default authkitMiddleware({ debug: true });
export const config = { matcher: ['/', '/admin'] };
```

--------------------------------

### Optional cookie configuration example

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Example usage of optional environment variables to configure cookie settings. WORKOS_COOKIE_MAX_AGE sets the maximum age in seconds, WORKOS_COOKIE_DOMAIN sets the cookie domain, and WORKOS_COOKIE_NAME sets the session cookie name.

```bash
WORKOS_COOKIE_MAX_AGE='600'
WORKOS_COOKIE_DOMAIN='example.com'
WORKOS_COOKIE_NAME='my-auth-cookie'
```

--------------------------------

### handleAuthkitProxy usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware-helpers.md

Example middleware proxy using handleAuthkitProxy. It protects /app by redirecting to the authorization URL (307 for GET, 303 for POST), handles a custom relative redirect with status 308, and falls back to passing through the request.

```ts
import { NextRequest } from 'next/server';
import { authkit, handleAuthkitProxy } from '@workos-inc/authkit-nextjs';

export default async function proxy(request: NextRequest) {
  const { session, headers, authorizationUrl } = await authkit(request);

  // Protect /app, redirecting with a 307 for GET and 303 for POST
  if (request.nextUrl.pathname.startsWith('/app') && !session.user && authorizationUrl) {
    return handleAuthkitProxy(request, headers, { redirect: authorizationUrl });
  }
  // Custom relative redirect
  if (request.nextUrl.pathname === '/old-path') {
    return handleAuthkitProxy(request, headers, { redirect: '/new-path', redirectStatus: 308 });
  }
  return handleAuthkitProxy(request, headers);
}
```

--------------------------------

### Example: authkitProxy in proxy.ts

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware.md

Example usage of authkitProxy in a proxy.ts file (Next.js 16+). Configures middlewareAuth, signUpPaths, eagerAuth, and refreshBufferSeconds, and sets the matcher to protect specific routes.

```typescript
// proxy.ts (Next.js 16+) — `export default authkitProxy()` and match pages that require auth
import { authkitProxy } from '@workos-inc/authkit-nextjs';

export default authkitProxy({
  middlewareAuth: { enabled: true, unauthenticatedPaths: ['/', '/about'] },
  signUpPaths: ['/account/sign-up'],
  eagerAuth: true,
  refreshBufferSeconds: 120,
});

export const config = { matcher: ['/', '/admin/:path*', '/about'] };
```

--------------------------------

### Advanced composition with partitionAuthkitHeaders and applyResponseHeaders

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware-helpers.md

Advanced composition example using partitionAuthkitHeaders and applyResponseHeaders. It rewrites to /app/dashboard with the partitioned request headers and applies the response headers to the rewritten response.

```ts
import { NextRequest, NextResponse } from 'next/server';
import { authkit, partitionAuthkitHeaders, applyResponseHeaders } from '@workos-inc/authkit-nextjs';

export default async function proxy(request: NextRequest) {
  const { headers } = await authkit(request);
  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, headers);

  const response = NextResponse.rewrite(new URL('/app/dashboard', request.url), {
    request: { headers: requestHeaders },
  });
  return applyResponseHeaders(response, responseHeaders);
}
```

--------------------------------

### Run wrangler dev

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/vinext/README.md

Starts the app in the local workerd runtime, matching production behavior more closely than vinext dev.

```bash
wrangler dev
```

--------------------------------

### Basic usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/impersonation.md

Shows how to render the Impersonation component inside an AuthKitProvider. Place it in your app layout to display the impersonation banner when applicable.

```tsx
import { Impersonation, AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function App() {
  return (
    <AuthKitProvider>
      <Impersonation />
      {/* Your app content */}
    </AuthKitProvider>
  );
}
```

--------------------------------

### withAuth usage example in app/account/page.tsx

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/session.md

Example server component that calls withAuth with ensureSignedIn: true to require authentication and access the user's feature flags.

```TypeScript
// app/account/page.tsx — server component
import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function AccountPage() {
  const { user, featureFlags } = await withAuth({ ensureSignedIn: true });
  return <div>Welcome {user.firstName}</div>;
}
```

--------------------------------

### Root layout with server-side initial auth

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/authkit-provider.md

Example root layout that fetches auth server-side with withAuth and passes the initialAuth (excluding accessToken) to AuthKitProvider, skipping the initial client-side fetch.

```tsx
import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';
import { withAuth } from '@workos-inc/authkit-nextjs';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const auth = await withAuth();
  const { accessToken, ...initialAuth } = auth;

  return (
    <html lang="en">
      <body>
        <AuthKitProvider initialAuth={initialAuth}>{children}</AuthKitProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### handleAuth

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/handle-auth.md

Documentation for the `handleAuth` function from the AuthKit Next.js SDK, including its options, return type, behavior, and examples.

```APIDOC
## `handleAuth`

### Description
Creates a GET route handler that completes the OAuth callback flow for AuthKit. It exchanges the authorization code for tokens, verifies the PKCE state, and establishes a session.

### Method
GET

### Endpoint
`/auth/callback` (must match `NEXT_PUBLIC_WORKOS_REDIRECT_URI`)

### Parameters
#### Options (HandleAuthOptions)
- **returnPathname** (string) - Optional - Pathname to redirect to after sign-in; default `'/'`.
- **baseURL** (string) - Optional - Base URL for the redirect (e.g. in Docker); must be a valid URL.
- **onSuccess** (function) - Optional - Callback invoked after successful authentication; receives `HandleAuthSuccessData`.
- **onError** (function) - Optional - Callback invoked on error; receives `{ error?, request }` and returns a `Response`.

### Request Example
```ts
import { handleAuth } from '@workos-inc/authkit-nextjs';

export const GET = handleAuth({ returnPathname: '/dashboard' });
```

### Response
#### Success Response (200)
- Redirects to the configured `returnPathname` (or `'/'`).
- Sets session cookie and deletes the PKCE cookie.
- Calls `onSuccess` if provided.

#### Error Response (500)
- Returns JSON `{ error: { message: 'Something went wrong', description: "Couldn't sign in. ..." } }` when no `onError` is provided.
- If `onError` is provided, its response is returned.

### Errors
- **Invalid baseURL** - Throws `Error('Invalid baseURL: <baseURL>')` at factory time if `baseURL` is not a valid URL.
- **Missing auth parameter** - Throws `CallbackError('Missing required auth parameter', 'missing_auth_params')` if `code` or `state` is missing.
- **Missing PKCE cookie** - Throws `CallbackError('Sign-in session could not be verified. Please try signing in again.', 'missing_pkce_cookie')` if the PKCE cookie is missing.
- **OAuth state mismatch** - Throws `CallbackError('OAuth state mismatch', 'oauth_state_mismatch')` if `state` does not match the PKCE cookie.
- **Missing tokens** - Throws `CallbackError('response is missing tokens', 'missing_tokens')` if the authentication response lacks `accessToken` or `refreshToken`.

### Example with side effects and error handling
```ts
import { handleAuth } from '@workos-inc/authkit-nextjs';
import { NextResponse } from 'next/server';

export const GET = handleAuth({
  returnPathname: '/dashboard',
  baseURL: 'https://my-app.example.com', // required behind Docker/proxies

  onSuccess: async ({ user, oauthTokens, authenticationMethod, organizationId, state }) => {
    await saveTokens(user.id, oauthTokens);
    const customData = state ? JSON.parse(state) : null;
    if (customData?.teamId) await addUserToTeam(user.id, customData.teamId);
  },

  onError: async ({ error, request }) => {
    console.error('Auth failed for', request.url, error);
    return NextResponse.redirect(new URL('/login?error=auth_failed', request.url));
  },
});
```
```

--------------------------------

### Composable proxy with callbacks

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/middleware.md

Example of using authkit in a proxy (Next.js 16+) or middleware (Next.js ≤15) with callbacks for session refresh success/error, and redirecting to authorization URL for protected routes.

```typescript
// proxy.ts (Next.js 16+) / middleware.ts (Next.js ≤15)
import { NextRequest } from 'next/server';
import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';

export default async function proxy(request: NextRequest) {
  const { session, headers, authorizationUrl } = await authkit(request, {
    onSessionRefreshSuccess: async ({ accessToken, user }) => {
      console.log(`Session refreshed for ${user.email}`);
    },
    onSessionRefreshError: async ({ error, isTransient }) => {
      console.error('Refresh failed (transient:', isTransient + ')', error);
    },
  });

  if (request.nextUrl.pathname.startsWith('/app') && !session.user && authorizationUrl) {
    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl });
  }
  return handleAuthkitHeaders(request, headers);
}
```

--------------------------------

### useAuth

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/authkit-provider.md

Documentation for the useAuth hook, including its parameters, return type, overloads, and usage examples.

```APIDOC
## useAuth

### Description
A React hook that provides access to the authentication context within an AuthKitProvider. It can optionally trigger a client-side redirect to AuthKit when the user is not signed in.

### Method
useAuth

### Parameters
- `ensureSignedIn` (boolean) - Optional, default `false` - When `true`, triggers `getAuth({ ensureSignedIn: true })` (client-side redirect to AuthKit) if there is no user and not loading.

### Returns
`AuthContextType` - The authentication context object.

### Throws
`Error('useAuth must be used within an AuthKitProvider')` when called outside the provider.

### Overloads
- `useAuth({ ensureSignedIn: true })` → `AuthContextType & ({ loading: true; user: User | null } | { loading: false; user: User })` — type narrows `user` to `User` once loading finishes.
- `useAuth()` / `useAuth({ ensureSignedIn: false })` → `AuthContextType`.

### Example
```tsx
'use client';
import { useAuth } from '@workos-inc/authkit-nextjs/components';

export default function AccountButton() {
  const { user, loading, signOut } = useAuth({ ensureSignedIn: true });

  if (loading) return <div>Loading...</div>;

  return (
    <button onClick={() => signOut({ returnTo: '/' })}>
      Sign out {user.firstName}
    </button>
  );
}
```

### Example — organization switching with error handling
```tsx
'use client';
import { useAuth } from '@workos-inc/authkit-nextjs/components';

function OrganizationSwitcher() {
  const { switchToOrganization } = useAuth();

  const handleSwitch = async () => {
    const result = await switchToOrganization('org_123', { revalidationStrategy: 'none' });
    if ('error' in result) {
      console.error('Switch failed:', result.error);
    }
  };

  return <button onClick={handleSwitch}>Switch org</button>;
}
```
```

--------------------------------

### Example: app/sign-in/route.ts using getSignInUrl

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Next.js route handler that calls getSignInUrl with returnTo and state, then redirects to the returned URL. Used as the Initiate Login URI in the WorkOS dashboard.

```typescript
// app/sign-in/route.ts — used as the Initiate Login URI in the WorkOS dashboard
import { getSignInUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export const GET = async () => {
  const signInUrl = await getSignInUrl({
    returnTo: '/dashboard',
    state: JSON.stringify({ referrer: 'homepage' }),
  });
  return redirect(signInUrl);
};
```

--------------------------------

### Custom auth flow with raw client

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/workos.md

Example of using getWorkOS in a custom authentication flow, including email verification and session saving.

```typescript
import { getWorkOS, saveSession } from '@workos-inc/authkit-nextjs';

async function verifyEmail(req: NextRequest) {
  const { code } = await req.json();
  const authResponse = await getWorkOS().userManagement.authenticateWithEmailVerification({
    clientId: process.env.WORKOS_CLIENT_ID,
    code,
  });
  await saveSession(authResponse, req);
  return Response.redirect('/dashboard');
}
```

--------------------------------

### getSignUpUrl usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Example usage of getSignUpUrl in a Next.js route handler. Calls getSignUpUrl with an organizationId and redirects to the returned sign-up URL.

```ts
import { getSignUpUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export const GET = async () => {
  const signUpUrl = await getSignUpUrl({ organizationId: 'org_123' });
  return redirect(signUpUrl);
};
```

--------------------------------

### Set up WorkOS callback route with handleAuth

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Creates the callback route handler for WorkOS authentication. Place this in the file matching your WORKOS_REDIRECT_URI, e.g., /app/auth/callback/route.ts.

```ts
import { handleAuth } from '@workos-inc/authkit-nextjs';

export const GET = handleAuth();
```

--------------------------------

### saveSession usage example

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/session.md

Example usage of saveSession in a custom email verification flow. Authenticates with WorkOS and saves the session, supporting both NextRequest and URL string forms.

```TypeScript
import { saveSession, getWorkOS } from '@workos-inc/authkit-nextjs';

async function handleEmailVerification(req: NextRequest) {
  const { code } = await req.json();
  const authResponse = await getWorkOS().userManagement.authenticateWithEmailVerification({
    clientId: process.env.WORKOS_CLIENT_ID,
    code,
  });
  await saveSession(authResponse, req);          // NextRequest form
  // or: await saveSession(authResponse, 'https://example.com/callback'); // URL string form
  return Response.redirect('/dashboard');
}
```

--------------------------------

### switchToOrganization

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Documentation for the switchToOrganization function from the WorkOS AuthKit Next.js SDK.

```APIDOC
## switchToOrganization

### Description
Switches the current session to a different organization and returns the fresh session information for that organization. It handles redirects for WorkOS API-key-migration, SSO, and MFA enrollment flows.

### Method
Function

### Signature
```ts
export async function switchToOrganization(
  organizationId: string,
  options: SwitchToOrganizationOptions = {},
): Promise<UserInfo>
```

### Parameters
- **organizationId** (string) - Required - The organization to switch the session to
- **options** (SwitchToOrganizationOptions) - Optional - See table below

#### SwitchToOrganizationOptions
- **returnTo** (string) - Optional - Pathname to revalidate/redirect to; defaults to the 'x-url' header or '/'
- **revalidationStrategy** ('none' | 'tag' | 'path') - Optional - Default 'path'
- **revalidationTags** (string[]) - Optional - Tags passed to revalidateTag when strategy is 'tag'

### Returns
`Promise<UserInfo>` - The fresh session (`user`, `sessionId`, `organizationId`, `role`, `roles`, `permissions`, `entitlements`, `featureFlags`, `impersonator`, `accessToken`) for the target organization.

### Behavior
- Calls `refreshSession({ organizationId, ensureSignedIn: true })`.
- If the refresh throws with `cause.rawData.authkit_redirect_url`, redirects there (WorkOS API-key-migration flow).
- If `cause.error === 'sso_required'` or `'mfa_enrollment'`, initiates a new PKCE sign-in for that organization via `getAuthURLAndSetPKCECookie({ organizationId })` and redirects.
- Any other error is re-thrown (typically a `TokenRefreshError`).
- After a successful refresh, revalidates (`revalidatePath(pathname)` for 'path', `revalidateTagCompat(tag)` for 'tag') and, unless strategy is 'none', `redirect(pathname)`.

### Example
```ts
'use server';
import { switchToOrganization } from '@workos-inc/authkit-nextjs';

export async function switchOrg(formData: FormData) {
  const orgId = formData.get('organizationId') as string;
  await switchToOrganization(orgId, {
    returnTo: '/app',
    revalidationStrategy: 'tag',
    revalidationTags: ['dashboard-data'],
  });
}
```
```

--------------------------------

### Get current user in a client component with useAuth

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Use the useAuth hook in a client component to get the current user session. The hook returns a loading flag to handle asynchronous loading states.

```jsx
'use client';
// Note the updated import path
import { useAuth } from '@workos-inc/authkit-nextjs/components';

export default function MyComponent() {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user, loading } = useAuth();

  if (loading) {
    return <div>Loading...</div>;
  }

  return <div>{user?.firstName}</div>;
}
```

--------------------------------

### Example: custom claims with generics

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/use-token-claims.md

Example component that uses useTokenClaims with a generic type parameter to access custom claims. It returns null when the workspace_id claim is missing, which happens when the token is absent or fails to parse.

```tsx
'use client';
import { useTokenClaims } from '@workos-inc/authkit-nextjs/components';

interface CustomClaims {
  workspace_id: string;
  plan: 'free' | 'pro';
}

function PlanBadge() {
  const claims = useTokenClaims<CustomClaims>();
  if (!claims.workspace_id) return null; // {} when no token/parse failure
  return <span className="badge">{claims.plan}</span>;
}
```

--------------------------------

### Copy and populate environment file

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/vinext/README.md

Copies the environment file to set WorkOS credentials. The required variables WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_COOKIE_PASSWORD (at least 32 characters), and NEXT_PUBLIC_WORKOS_REDIRECT_URI (default http://localhost:3000/callback) must be filled in.

```bash
cp .env.local.example .env.local
```

--------------------------------

### Example: standard claims with useTokenClaims

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/use-token-claims.md

Example component that uses useTokenClaims to display standard claims such as org_id, role, and iat. The iat timestamp is converted to an ISO string. Falls back to 'none' or 'n/a' when claims are missing.

```tsx
'use client';
import { useTokenClaims } from '@workos-inc/authkit-nextjs/components';

function SessionMeta() {
  const { org_id, role, iat } = useTokenClaims();

  return (
    <dl>
      <dt>Organization</dt><dd>{org_id ?? 'none'}</dd>
      <dt>Role</dt><dd>{role ?? 'none'}</dd>
      <dt>Issued at</dt><dd>{iat ? new Date(iat * 1000).toISOString() : 'n/a'}</dd>
    </dl>
  );
}
```

--------------------------------

### Example: Decode token claims with getTokenClaims and custom type

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/session.md

Example usage of getTokenClaims to retrieve custom claims from the decoded token. The claims include org_id, and the type parameter T defines custom_claim as a string. Returns an empty object when no token is available.

```ts
import { getTokenClaims } from '@workos-inc/authkit-nextjs';

const claims = await getTokenClaims<{ custom_claim: string }>();
console.log(claims.custom_claim, claims.org_id);
```

--------------------------------

### getSignInUrl implementation

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/auth.md

Server-only helper that builds the AuthKit sign-in URL and sets the PKCE cookie. It maps returnTo to returnPathname and forces screenHint to 'sign-in'. Returns a Promise<string> and seals OAuth state with iron-session (ttl: 600).

```typescript
type GetSignUrlOptions = Omit<GetAuthURLOptions, 'screenHint' | 'returnPathname'> & {
  returnTo?: string;
};

export async function getSignInUrl(authUrlOptions: GetSignUrlOptions = {}) {
  return getAuthURLAndSetPKCECookie({
    ...authUrlOptions,
    returnPathname: authUrlOptions.returnTo,
    screenHint: 'sign-in',
  });
}
```

--------------------------------

### Example: Use checkRecentAuth to guard a sensitive action (maxAge: 300)

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/session.md

Example usage of checkRecentAuth in a Next.js server action. It forces reauthentication when the user's auth is older than 300 seconds by redirecting to the sign-in URL with the maxAge option. Requires @workos-inc/node >= 10.7.0.

```ts
'use server';
import { checkRecentAuth, getSignInUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export async function deleteAccount() {
  const { isStale } = await checkRecentAuth({ maxAge: 300 });
  if (isStale) {
    redirect(await getSignInUrl({ maxAge: 300 })); // force OIDC max_age reauth
  }
  // ...perform sensitive action
}
```

--------------------------------

### useRecentAuth

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/use-recent-auth.md

Documentation for the useRecentAuth hook, including its signature, parameters, return values, and usage examples.

```APIDOC
## `useRecentAuth`

### Description
Reports how recently the current user authenticated, from the `auth_time` claim already held in client memory. Presentation only — enforce recency server-side with `checkRecentAuth`.

### Signature
`useRecentAuth({ maxAge }: { maxAge: number })`

### Parameters
- `maxAge` (number) - Required - Maximum elapsed seconds since `auth_time` for the authentication to be considered recent.

### Return Value
Returns one of two `as const` shapes:

While the token is loading:
```ts
{ loading: true; authenticatedAt: undefined; isStale: undefined }
```

Otherwise:
```ts
{ loading: false; authenticatedAt: Date | null; isStale: boolean }
```

| Property | Type | Description |
|----------|------|-------------|
| `loading` | `boolean` | `true` while the access token is being fetched |
| `authenticatedAt` | `Date \| null \| undefined` | `Date` of the `auth_time` claim (`authTime * 1000`); `null` when the claim is missing/non-finite; `undefined` while loading |
| `isStale` | `boolean \| undefined` | `true` when `nowSeconds - authTime > maxAgeSeconds`; fails closed to `true` for missing `auth_time`; `undefined` while loading |

### Usage Notes
Presentation only — it reads the `auth_time` claim already in client memory and never redirects. Enforce recency on the server with `checkRecentAuth`; send users through re-authentication by redirecting to `getSignInUrl({ maxAge })`, which forwards OIDC `max_age`.

### Example — disable a sensitive button when auth is stale
```tsx
'use client';
import { useRecentAuth } from '@workos-inc/authkit-nextjs/components';

function SensitiveActionButton() {
  const { loading, isStale } = useRecentAuth({ maxAge: 300 });

  if (loading) {
    return <button disabled>Loading…</button>;
  }

  return (
    <button disabled={isStale}>
      {isStale ? 'Re-authenticate to continue' : 'Delete account'}
    </button>
  );
}
```

### Example — display last-auth time
```tsx
'use client';
import { useRecentAuth } from '@workos-inc/authkit-nextjs/components';

function LastAuthLabel() {
  const { loading, authenticatedAt } = useRecentAuth({ maxAge: 3600 });
  if (loading) return <span>Checking…</span>;
  return <span>Last authenticated: {authenticatedAt?.toLocaleString() ?? 'unknown'}</span>;
}
```
```

--------------------------------

### First-call options for getFeatureFlagsRuntimeClient

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/feature-flags.md

Shows how to pass options on the first call to `getFeatureFlagsRuntimeClient`. Because the client is memoized, only the options from the first call are used; any options passed on subsequent calls are ignored.

```ts
import { getFeatureFlagsRuntimeClient } from '@workos-inc/authkit-nextjs';

// Only this first call's options take effect
const client = getFeatureFlagsRuntimeClient({ timeoutMs: 10_000 });
```

--------------------------------

### Server-side flag evaluation with getFeatureFlagsRuntimeClient

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/feature-flags.md

Server-side flag evaluation example. Creates the runtime client once, waits for it to be ready with a 5-second timeout, and evaluates the `advanced-analytics` flag for the signed-in user. Errors from `waitUntilReady` are caught and logged; the flag result determines which component to render.

```ts
import { getFeatureFlagsRuntimeClient, withAuth } from '@workos-inc/authkit-nextjs';

const featureFlags = getFeatureFlagsRuntimeClient();

export default async function DashboardPage() {
  const { user, organizationId } = await withAuth({ ensureSignedIn: true });

  try {
    await featureFlags.waitUntilReady({ timeoutMs: 5000 });
  } catch (error) {
    console.error('Feature flags client failed to initialize:', error);
  }

  const enabled = featureFlags.isEnabled('advanced-analytics', {
    userId: user.id,
    organizationId,
  });

  return enabled ? <AdvancedAnalytics /> : <BasicAnalytics />;
}
```

--------------------------------

### Deploy with pnpm run deploy

Source: https://github.com/workos/authkit-nextjs/blob/main/examples/vinext/README.md

Runs the deploy command. vinext auto-generates Cloudflare-specific build configuration and deploys to Workers.

```bash
pnpm run deploy
```

--------------------------------

### Impersonation Component

Source: https://github.com/workos/authkit-nextjs/blob/main/_autodocs/api-reference/components/impersonation.md

Documentation for the Impersonation React component from the AuthKit Next.js SDK, including its props, behavior, and usage examples.

```APIDOC
## `Impersonation` Component

### Description
Renders a fixed-position banner when the current user is being impersonated, showing the impersonated user's email and organization, with a "Stop" button to end impersonation. It reads authentication state via `useAuth()` and fetches the impersonated user's organization via `getOrganizationAction`.

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `side` | `'top' \| 'bottom'` | No | `'bottom'` | Vertical placement of the banner. |
| `returnTo` | `string \| undefined` | No | `undefined` | Passed to `handleSignOutAction({ returnTo })` for the "Stop" (end impersonation) action. |
| `...props` | `React.ComponentPropsWithoutRef<'div'>` | No | — | Spread onto the root `<div>` (e.g. `className`, `style`). |

### Returns
- A fixed-position overlay (`data-workos-impersonation-root`, `z-index: 9999`, `pointer-events: none` on the container) or `null` when the current user is not being impersonated (`!impersonator || !user`).

### Behavior
- Reads `user`, `impersonator`, `organizationId` from `useAuth()`.
- When impersonating, fetches the impersonated user's organization via `getOrganizationAction(organizationId)` (a server action that only resolves the organization matching the current session's `organizationId`, returning `{ id, name }` or `null`).
- The banner shows `You are impersonating <email> within the <organization name> organization` and a **Stop** button that calls `handleSignOutAction({ returnTo })`.
- Minimize/maximize toggles set the CSS variable `--wi-minimized` on the root element.
- Styling is fully controlled by CSS custom properties: `--wi-s` (size, default from `--workos-impersonation-size`, 4px → 15px), `--wi-bgc` (`--workos-impersonation-background-color`, default `#fce654`), `--wi-c` (`--workos-impersonation-color`, default `#1a1600`), `--wi-bc` (`--workos-impersonation-border-color`, default `#e0c36c`), `--wi-bw` (`--workos-impersonation-border-width`, default 1px).

### Requirements
Impersonation requires a configured **Initiate Login URI** in the WorkOS dashboard; otherwise WorkOS-initiated impersonation redirects fail authentication with `Missing required auth parameter` (see [errors.md](../errors.md)).

### Example — basic

```tsx
import { Impersonation, AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function App() {
  return (
    <AuthKitProvider>
      <Impersonation />
      {/* Your app content */}
    </AuthKitProvider>
  );
}
```

### Example — customized placement and sign-out target

```tsx
'use client';
import { Impersonation } from '@workos-inc/authkit-nextjs/components';

export function ImpersonationBanner() {
  return (
    <Impersonation
      side="top"
      returnTo="https://your-app.com/admin"
      style={{ '--workos-impersonation-background-color': '#0f172a' } as React.CSSProperties}
    />
  );
}
```
```

--------------------------------

### Initiate login URI route with getSignInUrl

Source: https://github.com/workos/authkit-nextjs/blob/main/README.md

Creates a Next.js route that initiates the AuthKit sign-in flow by calling getSignInUrl() and redirecting to the returned URL. This route must be set as the Initiate login URI in the WorkOS dashboard Redirects tab (e.g., http://localhost:3000/sign-in). Required for impersonation and other WorkOS-initiated flows to complete PKCE/CSRF verification.

```ts
// app/sign-in/route.ts (or app/login/route.ts)
import { getSignInUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export const GET = async () => {
  const signInUrl = await getSignInUrl();
  return redirect(signInUrl);
};
```
Tokens:
Raw