AuthKit TanStack Start

Authentication and session management for TanStack Start applications using WorkOS AuthKit.

Note

This library is designed for TanStack Start v1.0+. TanStack Start is currently in beta - expect some API changes as the framework evolves.

Installation

npm install @workos/authkit-tanstack-react-start

pnpm add @workos/authkit-tanstack-react-start

Quickstart

Environment Variables

Create a .env file in your project root with the following required variables:

WORKOS_CLIENT_ID="client_..."      # Get from WorkOS dashboard
WORKOS_API_KEY="sk_test_..."       # Get from WorkOS dashboard
WORKOS_REDIRECT_URI="http://localhost:3000/api/auth/callback"
WORKOS_COOKIE_PASSWORD="..."       # Min 32 characters

Generate a secure cookie password (32+ characters):

openssl rand -base64 24

Optional Configuration

Variable	Default	Description
`WORKOS_COOKIE_MAX_AGE`	`34560000` (400 days)	Cookie lifetime in seconds
`WORKOS_COOKIE_NAME`	`wos-session`	Session cookie name
`WORKOS_COOKIE_DOMAIN`	None	Cookie domain (for multi-domain sessions)
`WORKOS_COOKIE_SAMESITE`	`lax`	SameSite attribute (`lax`, `strict`, `none`)
`WORKOS_API_HOSTNAME`	`api.workos.com`	WorkOS API hostname

Setup (3 Steps)

1. Configure Middleware

Create or update src/start.ts:

import { createStart } from '@tanstack/react-start';
import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

export const startInstance = createStart(() => ({
  requestMiddleware: [authkitMiddleware()],
}));

2. Create Callback Route

Create src/routes/api/auth/callback.tsx:

import { createFileRoute } from '@tanstack/react-router';
import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/callback')({
  server: {
    handlers: {
      GET: handleCallbackRoute(),
    },
  },
});

Make sure this matches your WORKOS_REDIRECT_URI environment variable.

3. Add Provider (Optional - only needed for client hooks)

If you want to use useAuth() or other client hooks, wrap your app with AuthKitProvider in src/routes/__root.tsx:

import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';
import { Outlet, createRootRoute } from '@tanstack/react-router';

export const Route = createRootRoute({
  component: RootComponent,
});

function RootComponent() {
  return (
    <AuthKitProvider>
      <Outlet />
    </AuthKitProvider>
  );
}

If you're only using server-side authentication (getAuth() in loaders), you can skip this step.

WorkOS Dashboard Configuration

Go to WorkOS Dashboard and navigate to the Redirects page.
Under Redirect URIs, add your callback URL: http://localhost:3000/api/auth/callback
Under Sign-out redirect, set the URL where you want users to be redirected after signing out. If you don't set a sign-out redirect URL, you must set the App homepage URL instead — WorkOS will redirect users there when no sign-out redirect is specified.

Note: If you don't set either the Sign-out redirect or the App homepage URL, WorkOS will redirect users to an error page.

Usage

Server-Side Authentication

Use getAuth() in route loaders or server functions to access the current session:

import { createFileRoute, redirect } from '@tanstack/react-router';
import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    const { user } = await getAuth();

    if (!user) {
      const signInUrl = await getSignInUrl();
      throw redirect({ href: signInUrl });
    }

    return { user };
  },
  component: DashboardPage,
});

function DashboardPage() {
  const { user } = Route.useLoaderData();
  return <div>Welcome, {user.firstName}!</div>;
}

Client-Side Hooks

For client components that need reactive auth state, use the useAuth() hook:

'use client'; // Not actually needed in TanStack Start, but shows intent

import { useAuth } from '@workos/authkit-tanstack-react-start/client';

function ProfileButton() {
  const { user, loading, signOut } = useAuth();

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

  if (!user) return <a href="/signin">Sign In</a>;

  return (
    <div>
      <span>{user.email}</span>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

Signing Out

Server-side (in route loader):

import { signOut } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/logout')({
  loader: async () => {
    await signOut(); // Redirects to WorkOS logout, then back to '/'
  },
});

Client-side (from useAuth hook):

const { signOut } = useAuth();

await signOut({ returnTo: '/goodbye' });

Organization Switching

Switch the active organization for multi-org users:

Server-side:

import { switchToOrganization } from '@workos/authkit-tanstack-react-start';

// In a server function or loader
const auth = await switchToOrganization({
  data: { organizationId: 'org_456' },
});

// Session now has org_456's role, permissions, etc.

Client-side:

const { switchToOrganization, organizationId } = useAuth();

await switchToOrganization('org_456');
// Auth state updates automatically

Protected Routes

Use layout routes to protect multiple pages:

// src/routes/_authenticated.tsx
import { createFileRoute, redirect } from '@tanstack/react-router';
import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/_authenticated')({
  loader: async ({ location }) => {
    const { user } = await getAuth();

    if (!user) {
      const signInUrl = await getSignInUrl({
        data: { returnPathname: location.pathname },
      });
      throw redirect({ href: signInUrl });
    }

    return { user };
  },
});

// Now all routes under _authenticated require auth:
// - _authenticated/dashboard.tsx
// - _authenticated/profile.tsx
// etc.

API Reference

Server Functions

These functions can be called from route loaders, server functions, or server route handlers.

`getAuth()`

Retrieves the current user session.

const { user } = await getAuth();

if (user) {
  console.log(user.email);
  console.log(user.firstName);
}

Returns: UserInfo | NoUserInfo

UserInfo fields:

user - The authenticated user object
sessionId - WorkOS session ID
organizationId - Active organization (if in org context)
role - User's role in the organization
roles - Array of role strings
permissions - Array of permission strings
entitlements - Array of entitlement strings
featureFlags - Array of feature flag strings
impersonator - Impersonator details (if being impersonated)
accessToken - JWT access token

`signOut(options?)`

Signs out the current user and redirects to WorkOS logout.

await signOut();
await signOut({ data: { returnTo: '/goodbye' } });

Options:

returnTo - Path to redirect to after logout (default: /)

`switchToOrganization(options)`

Switches to a different organization and refreshes the session with new claims.

const auth = await switchToOrganization({
  data: {
    organizationId: 'org_123',
    returnTo: '/dashboard', // optional
  },
});

Options:

organizationId - The organization ID to switch to (required)
returnTo - Path to redirect to if auth fails

Returns: UserInfo with updated organization claims

`getSignInUrl(options?)`

Generates a sign-in URL for redirecting to AuthKit.

// Basic usage
const url = await getSignInUrl();

// With return path
const url = await getSignInUrl({
  data: { returnPathname: '/dashboard' },
});

Options:

returnPathname - Path to return to after sign-in

`getSignUpUrl(options?)`

Generates a sign-up URL for redirecting to AuthKit.

const url = await getSignUpUrl();
const url = await getSignUpUrl({
  data: { returnPathname: '/onboarding' },
});

Options:

returnPathname - Path to return to after sign-up

`getAuthorizationUrl(options)`

Advanced: Generate a custom authorization URL with full control.

const url = await getAuthorizationUrl({
  data: {
    screenHint: 'sign-in',
    returnPathname: '/dashboard',
    redirectUri: 'https://example.com/callback', // override default
  },
});

Options:

screenHint - 'sign-in' or 'sign-up'
returnPathname - Return path after authentication
redirectUri - Override the default redirect URI

Route Handlers

`handleCallbackRoute`

Handles the OAuth callback from WorkOS. Use this in your callback route.

Basic usage:

import { createFileRoute } from '@tanstack/react-router';
import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/callback')({
  server: {
    handlers: {
      GET: handleCallbackRoute(),
    },
  },
});

With hooks for custom logic:

export const Route = createFileRoute('/api/auth/callback')({
  server: {
    handlers: {
      GET: handleCallbackRoute({
        onSuccess: async ({ user, authenticationMethod }) => {
          // Create user record in your database
          await db.users.upsert({ id: user.id, email: user.email });
          // Track analytics
          analytics.track('User Signed In', { method: authenticationMethod });
        },
        onError: ({ error, request }) => {
          // Custom error handling
          console.error('Auth failed:', error);
          return new Response(JSON.stringify({ error: 'Authentication failed' }), {
            status: 500,
            headers: { 'Content-Type': 'application/json' },
          });
        },
      }),
    },
  },
});

Options:

onSuccess?: (data) => Promise<void> - Called after successful authentication with user data, tokens, and authentication method
onError?: ({ error, request }) => Response - Custom error handler that returns a Response
returnPathname?: string - Override the redirect path after authentication (defaults to state or /)

Client Hooks

Available from @workos/authkit-tanstack-react-start/client. Requires <AuthKitProvider> wrapper.

`useAuth(options?)`

Access authentication state and methods in client components.

import { useAuth } from '@workos/authkit-tanstack-react-start/client';

function MyComponent() {
  const { user, loading, signOut } = useAuth();

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Not signed in</div>;

  return (
    <div>
      <p>{user.email}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

Options:

ensureSignedIn?: boolean - If true, automatically triggers sign-in flow for unauthenticated users

Returns: AuthContextType with:

user - Current user or null
loading - Loading state
sessionId, organizationId, role, roles, permissions, entitlements, featureFlags, impersonator
getAuth() - Refresh auth state
refreshAuth(options) - Refresh session with optional org switch
signOut(options) - Sign out
switchToOrganization(orgId) - Switch organizations

`useAccessToken()`

Manage access tokens with automatic refresh.

import { useAccessToken } from '@workos/authkit-tanstack-react-start/client';

function ApiCaller() {
  const { accessToken, loading, getAccessToken } = useAccessToken();

  const callApi = async () => {
    const token = await getAccessToken(); // Always fresh

    const response = await fetch('/api/data', {
      headers: { Authorization: `Bearer ${token}` },
    });
  };

  return <button onClick={callApi}>Fetch Data</button>;
}

Returns:

accessToken - Current token (may be stale)
loading - Loading state
error - Last error or null
refresh() - Manually refresh token
getAccessToken() - Get guaranteed fresh token

`useTokenClaims()`

Parse and decode JWT claims from the access token.

import { useTokenClaims } from '@workos/authkit-tanstack-react-start/client';

function ClaimsDisplay() {
  const claims = useTokenClaims();

  if (!claims) return null;

  return (
    <div>
      <p>Session ID: {claims.sid}</p>
      <p>Organization: {claims.org_id}</p>
      <p>Role: {claims.role}</p>
    </div>
  );
}

Middleware

`authkitMiddleware(options?)`

Processes authentication on every request. Validates tokens, refreshes sessions, and provides auth context to server functions.

import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

// Basic usage
authkitMiddleware();

// With custom redirect URI (e.g., for Vercel preview deployments)
authkitMiddleware({
  redirectUri: 'https://preview-123.example.com/api/auth/callback',
});

Options:

redirectUri - Override the default redirect URI from WORKOS_REDIRECT_URI. Useful for dynamic environments like preview deployments.

TypeScript

This library is fully typed. Common types:

import type {
  User,
  Session,
  UserInfo,
  NoUserInfo,
  Impersonator
} from '@workos/authkit-tanstack-react-start';

// User object from WorkOS
const user: User = {
  id: string;
  email: string;
  firstName: string | null;
  lastName: string | null;
  emailVerified: boolean;
  profilePictureUrl: string | null;
  // ... more fields
};

// Auth result from getAuth()
const auth: UserInfo | NoUserInfo = await getAuth();

Route loaders get full type inference:

export const Route = createFileRoute('/profile')({
  loader: async () => {
    const { user } = await getAuth();
    return { user }; // Fully typed
  },
  component: ProfilePage,
});

function ProfilePage() {
  const { user } = Route.useLoaderData(); // user is typed!
}

How It Works

Server-Side Flow

Middleware runs on every request - validates/refreshes session, stores auth in context
Route loaders call getAuth() - retrieves auth from middleware context
No client bundle bloat - server functions create RPC boundaries automatically

Client-Side Flow (with Provider)

Provider wraps app - provides auth context to hooks
Hooks call server actions - fetch auth state via RPC
State updates automatically - on tab focus, refresh, org switch

Why the Provider is Optional

Server-only apps: Just use getAuth() in loaders - no provider needed
Client hooks needed: Add provider to use useAuth(), useAccessToken(), etc.
Flexibility: Start server-only, add client hooks later

Common Patterns

Sign In Flow

// Get sign-in URL in loader
export const Route = createFileRoute('/')({
  loader: async () => {
    const { user } = await getAuth();
    const signInUrl = await getSignInUrl();
    return { user, signInUrl };
  },
  component: HomePage,
});

function HomePage() {
  const { user, signInUrl } = Route.useLoaderData();

  if (!user) {
    return <a href={signInUrl}>Sign In with AuthKit</a>;
  }

  return <div>Welcome, {user.firstName}!</div>;
}

Protected Route Layout

// src/routes/_authenticated.tsx
import { createFileRoute, redirect } from '@tanstack/react-router';
import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/_authenticated')({
  loader: async ({ location }) => {
    const { user } = await getAuth();

    if (!user) {
      const signInUrl = await getSignInUrl({
        data: { returnPathname: location.pathname },
      });
      throw redirect({ href: signInUrl });
    }

    return { user };
  },
});

// All child routes require authentication:
// - _authenticated/dashboard.tsx
// - _authenticated/settings.tsx

Organization Switcher

import { useAuth } from '@workos/authkit-tanstack-react-start/client';

function OrgSwitcher() {
  const { organizationId, switchToOrganization } = useAuth();

  return (
    <select
      value={organizationId || ''}
      onChange={(e) => switchToOrganization(e.target.value)}
    >
      <option value="org_123">Acme Corp</option>
      <option value="org_456">Other Company</option>
    </select>
  );
}

Accessing User in Multiple Places

Loader (server-side):

loader: async () => {
  const { user, organizationId, role } = await getAuth();
  return { user, organizationId, role };
};

Component (from loader data):

function MyPage() {
  const { user } = Route.useLoaderData();
  // ...
}

Client hook (reactive):

function MyClientComponent() {
  const { user, loading } = useAuth();
  // Updates on session changes
}

Troubleshooting

"AuthKit middleware is not configured"

You forgot to add authkitMiddleware() to src/start.ts. See step 1 in setup.

"useAuth must be used within an AuthKitProvider"

You're calling useAuth() but haven't wrapped your app with <AuthKitProvider>. See step 3 in setup.

If you don't need client hooks, use getAuth() in loaders instead.

Environment variable errors on startup

The middleware validates configuration on first request. If you see errors about missing variables:

Check your .env file exists
Verify all required variables are set
Ensure WORKOS_COOKIE_PASSWORD is 32+ characters
Restart your dev server after changing env vars

Types not working / Import errors

Make sure you're importing from the right path:

// Server functions
import { getAuth, signOut } from '@workos/authkit-tanstack-react-start';

// Client hooks
import { useAuth } from '@workos/authkit-tanstack-react-start/client';

Don't import client hooks in server code or vice versa.

"can only be called on the server"

You're trying to call a server function from a beforeLoad hook or client component.

Wrong:

beforeLoad: async () => {
  const { user } = await getAuth(); // ❌ Runs on client during hydration
};

Right:

loader: async () => {
  const { user } = await getAuth(); // ✅ Server-only during SSR
};

Use useAuth() client hook for client components, or move logic to a loader.

Example Application

Check the /example directory for a complete working application demonstrating:

Server-side authentication in loaders
Client-side hooks with provider
Protected routes
Organization switching
Sign in/out flows
Access token management

Run it locally:

cd example
pnpm install
pnpm dev

Framework Compatibility

TanStack Start: v1.132.0+
TanStack Router: v1.132.0+
React: 18.0+
Node.js: 18+

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
.github		.github
example		example
src		src
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
LICENSE		LICENSE
README.md		README.md
context7.json		context7.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
prettier.config.js		prettier.config.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest-env.d.ts		vitest-env.d.ts
vitest.config.ts		vitest.config.ts

License

workos/authkit-tanstack-start

Folders and files

Latest commit

History

Repository files navigation

AuthKit TanStack Start

Installation

Quickstart

Environment Variables

Optional Configuration

Setup (3 Steps)

1. Configure Middleware

2. Create Callback Route

3. Add Provider (Optional - only needed for client hooks)

WorkOS Dashboard Configuration

Usage

Server-Side Authentication

Client-Side Hooks

Signing Out

Organization Switching

Protected Routes

API Reference

Server Functions

getAuth()

signOut(options?)

switchToOrganization(options)

getSignInUrl(options?)

getSignUpUrl(options?)

getAuthorizationUrl(options)

Route Handlers

handleCallbackRoute

Client Hooks

useAuth(options?)

useAccessToken()

useTokenClaims()

Middleware

authkitMiddleware(options?)

TypeScript

How It Works

Server-Side Flow

Client-Side Flow (with Provider)

Why the Provider is Optional

Common Patterns

Sign In Flow

Protected Route Layout

Organization Switcher

Accessing User in Multiple Places

Troubleshooting

"AuthKit middleware is not configured"

"useAuth must be used within an AuthKitProvider"

Environment variable errors on startup

Types not working / Import errors

"can only be called on the server"

Example Application

Framework Compatibility

Related

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

`getAuth()`

`signOut(options?)`

`switchToOrganization(options)`

`getSignInUrl(options?)`

`getSignUpUrl(options?)`

`getAuthorizationUrl(options)`

`handleCallbackRoute`

`useAuth(options?)`

`useAccessToken()`

`useTokenClaims()`

`authkitMiddleware(options?)`

Packages