AuthKit TanStack Start

https://github.com/workos/authkit-tanstack-start
Admin
Provides authentication and session management for TanStack Start applications using WorkOS AuthKit.
Tokens:39,158
Snippets:476
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run Example Application Locally

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

Commands to navigate to the example directory, install dependencies, and start the development server.

```bash
cd example
pnpm install
pnpm dev
```

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

### Install AuthKit TanStack Start

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

Install the required package using npm or pnpm.

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

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

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

### Run Development Server

Source: https://github.com/workos/authkit-tanstack-start/blob/main/example/README.md

Start the development server for the example application. After running this command, navigate to http://localhost:3000 in your browser.

```bash
pnpm dev
```

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

### Registering authkitMiddleware in TanStack Start

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Configuration example for integrating AuthKit middleware into the TanStack Start instance.

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

export const startInstance = createStart(() => ({
  requestMiddleware: [
    createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' }),
    authkitMiddleware(),
  ],
}));
```

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

### Development Commands

Source: https://github.com/workos/authkit-tanstack-start/blob/main/CLAUDE.md

Standard commands for installing dependencies, running the development server, building the project, and starting the production server.

```bash
pnpm install
pnpm dev       # port 3000
pnpm build     # includes typecheck
pnpm start     # production
```

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

### Basic OAuth callback setup

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/05-callback-handler.md

Minimal implementation of the callback route handler within a TanStack Start route.

```typescript
// 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(),
    },
  },
});
```

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

### Get Authorization URL Usage Example

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Example of generating an authorization URL with custom options.

```typescript
const url = await getAuthorizationUrl({
  data: {
    screenHint: 'signin',
    returnPathname: '/app',
    organizationId: 'org_123', // Suggest org
  },
});
```

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

### Implement sign-in route handler

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Example of using getSignInUrl within a TanStack Start server route handler.

```typescript
// src/routes/api/auth/sign-in.tsx
import { createFileRoute } from '@tanstack/react-router';
import { getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/sign-in')({
  server: {
    handlers: {
      GET: async ({ request }) => {
        const returnPathname = new URL(request.url).searchParams.get('return') || '/';
        const url = await getSignInUrl({ data: { returnPathname } });
        return Response.redirect(url);
      },
    },
  },
});
```

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

### Basic AuthKitProvider Setup

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Standard implementation of the provider in a root layout.

```typescript
// src/routes/__root.tsx
import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';

export function RootLayout({ children }) {
  return (
    <AuthKitProvider>
      {children}
    </AuthKitProvider>
  );
}
```

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

### Switch Organization Usage Examples

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Examples for switching organizations, including standard usage and usage with a redirect.

```typescript
const auth = await switchToOrganization({
  data: { organizationId: 'org_123' },
});

console.log(`Switched to org ${auth.organizationId}`);
console.log(`Role: ${auth.role}`);
console.log(`Permissions: ${auth.permissions}`);
```

```typescript
// Redirect happens after session is refreshed
await switchToOrganization({
  data: {
    organizationId: 'org_456',
    returnTo: '/workspace',
  },
});
```

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

### Get Access Token Usage

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Example of retrieving the current session access token.

```typescript
const token = await getAccessTokenAction();
if (token) {
  // Use token for downstream API call
} else {
  console.log('No token available');
}
```

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

### OAuth Provider Token Examples

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/05-callback-handler.md

Illustrates the varying structures of OAuth tokens for Google and Microsoft providers.

```typescript
// Google OAuth tokens
const googleTokens = {
  access_token: 'ya29...',
  refresh_token: '1//0g...',
  scope: 'openid email profile',
  token_type: 'Bearer',
  expiry_date: 1234567890,
};

// Microsoft OAuth tokens
const msTokens = {
  access_token: 'eyJ0eXAiOi...',
  refresh_token: 'M.R3_BAY...',
  scope: 'openid email profile',
  token_type: 'Bearer',
  expires_in: 3600,
};
```

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

### Handling server-only functions

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

Demonstrates the correct placement of server-side authentication checks within TanStack Start loaders.

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

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

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

### authkitMiddleware()

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Middleware for TanStack Start that validates and refreshes sessions, and makes the AuthKit context available to downstream handlers.

```APIDOC
## authkitMiddleware()

### Description
Middleware for TanStack Start that validates and refreshes sessions. It runs on every server request, parses and validates the session cookie, automatically refreshes expired access tokens, and stores the AuthKit context in TanStack's global context.

### Signature
`export function authkitMiddleware(options?: AuthKitMiddlewareOptions): ReturnType<typeof createMiddleware>`

### Parameters
- **options** (AuthKitMiddlewareOptions) - Optional - Middleware configuration object.

#### AuthKitMiddlewareOptions
- **redirectUri** (string) - Optional - Override callback redirect URI. Defaults to WORKOS_REDIRECT_URI environment variable.

### Usage Example
```typescript
import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

// Basic usage in createStart
authkitMiddleware();

// Usage with custom redirect URI
authkitMiddleware({
  redirectUri: process.env.WORKOS_REDIRECT_URI || 'http://localhost:3000/callback',
});
```
```

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

### Manual Session Check Example

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Example of manually invoking the session check to detect expiration.

```typescript
const { user } = useAuth();

const hasSession = await checkSessionAction();
if (!hasSession) {
  console.log('Session expired');
  // Trigger re-authentication
}
```

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

### Configuring Custom Redirect URI

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Example of overriding the default redirect URI for dynamic environments.

```typescript
authkitMiddleware({
  redirectUri: process.env.WORKOS_REDIRECT_URI || 'http://localhost:3000/callback',
})
```

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

### Refresh Auth Action Usage

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Example of refreshing the current session or switching organizations.

```typescript
const { refreshAuth } = useAuth();

// Refresh current session
await refreshAuth();

// Switch org and refresh
const result = await refreshAuth({ organizationId: 'org_123' });
if (result?.error) console.error(result.error);
```

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

### handleCallbackRoute()

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/05-callback-handler.md

Creates a route handler for OAuth authentication callback. This function is designed to be used within a TanStack Start server handler for GET requests.

```APIDOC
## handleCallbackRoute()

### Description
Creates a route handler for OAuth authentication callback. It extracts authorization codes, validates PKCE, exchanges tokens, and manages session state.

### Parameters
- **options** (HandleCallbackOptions) - Optional - Callback configuration object.

#### HandleCallbackOptions
- **returnPathname** (string) - Optional - Redirect path after successful authentication (default: `/`).
- **onSuccess** (function) - Optional - Callback function executed on successful authentication.
- **onError** (function) - Optional - Custom error handler function (overrides errorRedirectUrl).
- **errorRedirectUrl** (string) - Optional - URL or path to redirect to on error.

### Behavior
1. Extracts `code` and `state` from query parameters.
2. Validates PKCE verifier cookie matches state.
3. Exchanges code for tokens via WorkOS API.
4. Decrypts and stores session in secure cookie.
5. Deletes temporary PKCE verifier cookie.
6. Redirects to success URL or calls onSuccess callback.
7. On error: calls onError or redirects to errorRedirectUrl.

### Important
- Must match your `WORKOS_REDIRECT_URI` environment variable.
- Only accepts GET requests with `code` and `state` parameters.
- Returns 307 (temporary) redirect on success.
- Returns 400 (bad request) or 500 (server error) on failure.
```

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

### Accessing Authentication Success Data

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/05-callback-handler.md

Example implementation of the onSuccess callback demonstrating how to extract and utilize user information and tokens.

```typescript
onSuccess: async (data: HandleAuthSuccessData) => {
  const {
    user,
    accessToken,
    authenticationMethod,
    oauthTokens,
  } = data;

  // Get OAuth tokens from upstream provider (e.g., Google)
  if (oauthTokens?.access_token) {
    console.log('Has Google access token:', oauthTokens.access_token);
  }

  // Log authentication method
  console.log(`User ${user.email} authenticated via ${authenticationMethod}`);

  // Store access token if needed (though it's in the session cookie)
  if (accessToken) {
    // Your custom storage logic
  }
}
```

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

### Switch Organization Usage

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Example of calling switchToOrganizationAction to change the active organization context.

```typescript
import { switchToOrganizationAction } from '@workos/authkit-tanstack-react-start';

const auth = await switchToOrganizationAction({ data: { organizationId: 'org_456' } });
if ('user' in auth && auth.user) {
  console.log(`Switched to ${auth.organizationId}, role: ${auth.role}`);
}
```

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

### handleCallbackRoute

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

Handles the OAuth callback from WorkOS. This should be used within your TanStack Start server route handler for the callback path.

```APIDOC
## handleCallbackRoute

### Description
Handles the OAuth callback from WorkOS. Use this in your callback route to process authentication results.

### Parameters
- **onSuccess** (function) - Optional - Called after successful authentication with user data, tokens, and authentication method.
- **onError** (function) - Optional - Custom error handler that returns a Response.
- **errorRedirectUrl** (string) - Optional - URL to redirect to on callback failure when onError is not set.
- **returnPathname** (string) - Optional - Override the success-path redirect after authentication.
```

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

### Seeding Initial Auth State

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Usage of getAuthAction within a TanStack Start route loader to initialize the AuthKitProvider.

```typescript
import { getAuthAction } from '@workos/authkit-tanstack-react-start';

// From route loader
export const Route = createFileRoute('/')({
  loader: async () => {
    const auth = await getAuthAction();
    return { initialAuth: auth };
  },
  component: ({ loaderData }) => (
    <AuthKitProvider initialAuth={loaderData.initialAuth}>
      <App />
    </AuthKitProvider>
  ),
});
```

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

### Configure Middleware

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

Register the AuthKit middleware and CSRF protection in your TanStack Start instance. The CSRF middleware is required to maintain security when defining a custom startInstance.

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

// Reject cross-site requests to server-function RPC endpoints.
const csrfMiddleware = createCsrfMiddleware({
  filter: (ctx) => ctx.handlerType === 'serverFn',
});

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

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

### Perform Conditional Access Checks

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Example of checking the authentication state returned by getAuth to conditionally execute logic.

```typescript
const auth = await getAuth();
if (auth.user) {
  console.log(`Signed in as ${auth.user.email}`);
  console.log(`Organization: ${auth.organizationId}`);
} else {
  console.log('Not authenticated');
}
```

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

### Configure authkitMiddleware

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Initialize the middleware in src/start.ts with required options.

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

authkitMiddleware({
  redirectUri: 'https://preview.example.com/api/auth/callback',
})
```

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

### Configure Environment Variables

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

Define the necessary WorkOS credentials and session settings in your project's .env file.

```bash
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
```

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

### View package metadata

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

Displays the package configuration, including entry points and export definitions.

```json
{
  "name": "@workos/authkit-tanstack-react-start",
  "version": "0.11.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./client": {
      "types": "./dist/client/index.d.ts",
      "import": "./dist/client/index.js"
    }
  }
}
```

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

### Configure Environment Variables

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Environment variable settings for development and production environments.

```bash
WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback
WORKOS_API_KEY=sk_test_...  # Test key
WORKOS_COOKIE_SAMESITE=lax
```

```bash
WORKOS_REDIRECT_URI=https://app.example.com/api/auth/callback
WORKOS_API_KEY=sk_live_...  # Live key
WORKOS_COOKIE_SAMESITE=strict
# Use Secure flag (automatic with HTTPS)
```

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

### Get Authorization URL Function Definition

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Type definition for the getAuthorizationUrl function.

```typescript
export const getAuthorizationUrl: (
  options?: GetAuthURLOptions
) => Promise<string>
```

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

### Get Access Token Action Definition

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Type definition for the getAccessTokenAction function.

```typescript
export const getAccessTokenAction: () => Promise<string | undefined>
```

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

### Implement Sign-Up API Route

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Defines a server-side route handler to generate a sign-up URL and redirect the user to a specific path.

```typescript
// src/routes/api/auth/sign-up.tsx
import { getSignUpUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/sign-up')({
  server: {
    handlers: {
      GET: async () => {
        const url = await getSignUpUrl({ data: '/onboarding' });
        return Response.redirect(url);
      },
    },
  },
});
```

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

### Configure authkitMiddleware

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

Initialize authentication middleware in your application. Use the optional redirectUri parameter to override default settings for dynamic environments.

```typescript
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',
});
```

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

### Get AuthKit Context Signature

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

The function signature for retrieving the AuthKit context or null.

```typescript
export function getAuthKitContextOrNull(): AuthKitContext | null
```

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

### Get AuthKit Context Definition

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

The function signature for retrieving the current AuthKit context.

```typescript
export function getAuthKitContext(): AuthKitContext
```

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

### Generate sign-up URL with getSignUpUrl

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

Creates a URL for redirecting users to the AuthKit sign-up page.

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

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

### Import Basic Server Auth Utilities

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

Use these imports for server-side authentication logic including session retrieval and callback handling.

```typescript
import {
  getAuth,
  getSignInUrl,
  signOut,
  handleCallbackRoute,
} from '@workos/authkit-tanstack-react-start';
```

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

### Generate sign-in URL with return path

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Retrieve a sign-in URL with a shorthand return path string.

```typescript
const url = await getSignInUrl({ data: '/dashboard' });
```

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

### Get AuthKit Service Signature

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

The function signature for retrieving or initializing the AuthKit service instance.

```typescript
export function getAuthkit(): Promise<AuthService<Request, Response>>
```

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

### Get Organization Action

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Fetches organization details by ID, ensuring the user is a member of the requested organization.

```typescript
export const getOrganizationAction: (organizationId: string) => Promise<OrganizationInfo | null>
```

```typescript
const org = await getOrganizationAction({ data: 'org_123' });
if (org) {
  console.log(`Organization: ${org.name}`);
} else {
  console.log('Not a member of this organization');
}
```

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

### Configure Dynamic Redirect URI

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/09-errors.md

Handle dynamic URLs in preview environments by configuring the redirect URI in the middleware.

```typescript
authkitMiddleware({
  redirectUri: `https://${process.env.VERCEL_URL}/api/auth/callback`,
})
```

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

### Package Metadata Configuration

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

The package metadata defining the entry points for the client module.

```json
{
  "main": "./dist/client/index.js",
  "types": "./dist/client/index.d.ts"
}
```

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

### Enforcing Auth Recency Server-Side

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/02-client-hooks.md

Example of using checkRecentAuth to enforce authentication recency before performing sensitive actions.

```typescript
import { checkRecentAuth } from '@workos/authkit-tanstack-react-start';

async function handleSensitiveAction() {
  const { isStale } = await checkRecentAuth({ maxAge: 300 });
  if (isStale) {
    // Redirect to sign-in with maxAge to force re-auth
    const url = await getSignInUrl({ data: { maxAge: 0 } });
    window.location.href = url;
    return;
  }
  // Proceed with action
}
```

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

### Configure AuthKitProvider in Root Layout

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Wraps the application with the AuthKit provider to manage authentication state and session expiration.

```typescript
import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';

export function RootLayout() {
  return (
    <AuthKitProvider
      onSessionExpired={() => {
        window.location.href = '/login';
      }}
    >
      <Outlet />
    </AuthKitProvider>
  );
}
```

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

### Generate Sign-Up URL

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Retrieves the absolute URL for the AuthKit sign-up page, optionally specifying a return path.

```typescript
export const getSignUpUrl: (
  data?: string | SignInUrlOptions
) => Promise<string>
```

```typescript
const url = await getSignUpUrl({ data: '/onboarding' });
window.location.href = url;
```

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

### Bundle Check Script Execution

Source: https://github.com/workos/authkit-tanstack-start/blob/main/CLAUDE.md

Verify that the TanStack compiler is transforming the SDK's distribution files by checking for the presence of `createClientRpc`. This command should be run after development or upgrades.

```bash
cd example && pnpm dev
# In another terminal:
curl -s 'http://localhost:3000/@fs/<absolute>/dist/server/actions.js' | grep -c 'createClientRpc'
# Expect non-zero. If zero, the compiler is no longer transforming the SDK's dist —
# stop and pivot to HTTP-RPC.

```

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

### Get Current User in Server Function

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Retrieves the authenticated user and claims within a TanStack server function.

```typescript
import { createServerFn } from '@tanstack/react-start';
import { getAuthKitContext } from '@workos/authkit-tanstack-react-start';

export const myServerFn = createServerFn().handler(async () => {
  const { auth, request } = getAuthKitContext();
  const { user, claims } = auth();

  if (!user) {
    throw new Error('Not authenticated');
  }

  console.log(`User: ${user.email}, Org: ${claims?.org_id}`);
  return { user };
});
```

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

### AuthKitProvider with Initial Auth Loader

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Injecting pre-loaded authentication state from a loader to prevent UI flickering.

```typescript
export const Route = createRootRoute({
  loader: async () => {
    const initialAuth = await getAuthAction();
    return { initialAuth };
  },
  component: ({ loaderData }) => (
    <AuthKitProvider initialAuth={loaderData.initialAuth}>
      <Outlet />
    </AuthKitProvider>
  ),
});
```

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

### Displaying Stale Auth Warning

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/02-client-hooks.md

Example of using useRecentAuth to display a UI warning badge based on authentication age.

```typescript
import { useRecentAuth } from '@workos/authkit-tanstack-react-start/client';

export function AuthStatusBadge() {
  const { loading, isStale, authenticatedAt } = useRecentAuth({ maxAge: 300 }); // 5 minutes

  if (loading) return <span>Checking...</span>;
  if (isStale) return <span style={{ color: 'red' }}>Re-auth required</span>;

  const lastAuth = authenticatedAt ? new Date(authenticatedAt * 1000).toLocaleTimeString() : 'unknown';
  return <span>Authenticated at {lastAuth}</span>;
}
```

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

### getSignUpUrl()

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Generates an absolute URL for the WorkOS AuthKit sign-up page, including necessary PKCE verifier cookies.

```APIDOC
## getSignUpUrl()

### Description
Generates the sign-up URL for the WorkOS AuthKit OAuth flow. This function sets PKCE verifier cookies and uses the 'signup' screen hint.

### Signature
`getSignUpUrl(data?: string | SignInUrlOptions): Promise<string>`

### Parameters
- **data** (string | SignInUrlOptions) - Optional - A return path string or an options object.

### Return Type
`Promise<string>` - The absolute URL to the WorkOS AuthKit sign-up page.

### Example
```typescript
const url = await getSignUpUrl({ data: '/onboarding' });
window.location.href = url;
```
```

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

### Environment Variables Configuration

Source: https://github.com/workos/authkit-tanstack-start/blob/main/example/README.md

Configure your WorkOS client ID, API key, cookie password, and redirect URI in the .env file. The cookie password must be at least 32 characters long.

```bash
WORKOS_CLIENT_ID=<YOUR_CLIENT_ID>
WORKOS_API_KEY=<YOUR_API_SECRET_KEY>
WORKOS_COOKIE_PASSWORD=<YOUR_COOKIE_PASSWORD>
WORKOS_REDIRECT_URI=http://localhost:3000/callback
```

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

### switchToOrganization(options)

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

Switches the current session to a different organization.

```APIDOC
## switchToOrganization(options)

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

### Options
- **organizationId** (String) - The organization ID to switch to (required)
- **returnTo** (String) - Path to redirect to if auth fails
```

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

### JWT Access Token Claims Structure

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/00-index.md

Example of the claims contained within an access token, which can be decoded using useTokenClaims or decodeJwt.

```typescript
{
  sid: "session_123",      // Session ID
  iss: "api.workos.com",   // Issuer
  sub: "user_123",         // Subject (user ID)
  org_id: "org_456",       // Organization
  role: "admin",           // Role in org
  permissions: ["read"],   // Permissions
  auth_time: 1234567890,   // Last auth (epoch seconds)
  exp: 1234571490,         // Expiration
}
```

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

### Main Entry Point Exports

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

The primary entry point for the package, re-exporting types and server-side symbols.

```typescript
export type { User, Impersonator, Session, AuthResult, BaseTokenClaims, CustomClaims } from './types.js';
export * from './server/index.js';
```

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

### Use switchToOrganization Method

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Switch to a different organization using the switchToOrganization method.

```typescript
const { switchToOrganization } = useAuth();

const result = await switchToOrganization('org_789');
```

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

  return (
    <select
      value={organizationId}
      onChange={async (e) => {
        const result = await switchToOrganization(e.target.value);
        if (result?.error) {
          console.error(result.error);
        }
      }}
    >
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name}
        </option>
      ))}
    </select>
  );
}
```

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

### Optional Environment Variables

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Additional configuration variables to customize cookie behavior and API endpoints.

```bash
WORKOS_COOKIE_NAME=wos-session           # Default: wos-session
WORKOS_COOKIE_MAX_AGE=34560000           # Default: 400 days (in seconds)
WORKOS_COOKIE_DOMAIN=.example.com        # For multi-domain sessions
WORKOS_COOKIE_SAMESITE=lax               # Default: lax (lax|strict|none)
WORKOS_API_HOSTNAME=api.workos.com       # Default: api.workos.com
```

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

### Generate sign-in URL with full options

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Retrieve a sign-in URL using the full options object for custom state and return paths.

```typescript
const url = await getSignInUrl({
  data: {
    returnPathname: '/dashboard',
    state: 'my-custom-state-value',
  },
});
```

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

### OAuth URL Generation Best Practices

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Demonstrates the correct approach to generating sign-in URLs only upon user interaction to avoid premature cookie expiration.

```typescript
// ❌ Wrong: creates cookie that expires unused
export const Route = createFileRoute('/signin')({
  loader: async () => {
    const url = await getSignInUrl(); // Creates cookie!
    return { url };
  },
});

// ✅ Right: create URL only when user clicks
<button onClick={async () => {
  const url = await getSignInUrl();
  window.location.href = url;
}}>
  Sign In
</button>
```

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

### Generate basic sign-in URL

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/01-server-functions.md

Basic implementation to retrieve a sign-in URL and redirect the user.

```typescript
const url = await getSignInUrl();
// Navigate to WorkOS AuthKit
window.location.href = url;
```

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

### Create User Menu Component

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Displays user information and provides a sign-out action.

```typescript
export function UserMenu() {
  const { user, organizationId, role, signOut } = useAuth();

  if (!user) {
    return <div>Not signed in</div>;
  }

  return (
    <menu>
      <li>
        <strong>{user.email}</strong>
      </li>
      <li>
        Organization: {organizationId || 'None'}
        {role && ` (${role})`}
      </li>
      <li>
        <button onClick={() => signOut()}>
          Sign Out
        </button>
      </li>
    </menu>
  );
}
```

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

### Sign-In Button

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Redirect users to the AuthKit sign-in URL by dynamically importing the sign-in utility.

```typescript
function SignInButton() {
  const handleClick = async () => {
    const { getSignInUrl } = await import('@workos/authkit-tanstack-react-start');
    const url = await getSignInUrl();
    window.location.href = url;
  };

  return <button onClick={handleClick}>Sign In</button>;
}
```

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

### Importing AuthKit utilities

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

Correct import paths for server functions and client hooks to avoid module resolution errors.

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

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

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

### authkitMiddleware(options?)

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

Processes authentication on every request by validating tokens and refreshing sessions. It provides the necessary authentication context to server functions.

```APIDOC
## authkitMiddleware(options?)

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

### Parameters
#### Options
- **redirectUri** (string) - Optional - Override the default redirect URI from WORKOS_REDIRECT_URI. Useful for dynamic environments like preview deployments.

### Usage Example
```typescript
import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

// Basic usage
authkitMiddleware();

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

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

### Implement Sign-In API Route

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Defines a server-side route handler to generate a sign-in URL and redirect the user.

```typescript
// src/routes/api/auth/sign-in.tsx
import { getSignInUrl } from '@workos/authkit-tanstack-react-start';
import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/api/auth/sign-in')({
  server: {
    handlers: {
      GET: async ({ request }) => {
        const returnPath = new URL(request.url).searchParams.get('return') || '/';
        const url = await getSignInUrl({ data: { returnPathname: returnPath } });
        return Response.redirect(url);
      },
    },
  },
});
```

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

### Implement Sign In Flow with Loader

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

Use getAuth in a route loader to check session status and conditionally render a sign-in link.

```typescript
export const Route = createFileRoute('/')({
  loader: async () => {
    const { user } = await getAuth();
    return { user };
  },
  component: HomePage,
});

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

  if (!user) {
    return <a href="/api/auth/sign-in">Sign In with AuthKit</a>;
  }

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

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

### Configure WORKOS_API_KEY

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Set the server-side API key for token exchange and user management. Never commit this value to version control.

```bash
WORKOS_API_KEY=sk_test_abc123def456ghi789
```

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

### Pre-load authentication state with initialAuth

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Pass server-rendered authentication state to the provider to prevent UI flickering.

```typescript
export const Route = createFileRoute('/')({
  loader: async () => {
    const auth = await getAuthAction();
    return { initialAuth: auth };
  },
  component: ({ loaderData }) => (
    <AuthKitProvider initialAuth={loaderData.initialAuth}>
      <App />
    </AuthKitProvider>
  ),
});
```

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

### Create Sign-In Endpoint

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

Implement the sign-in route to initiate the AuthKit flow, which is required for features like impersonation.

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

export const Route = createFileRoute('/api/auth/sign-in')({
  server: {
    handlers: {
      GET: async ({ request }: { request: Request }) => {
        const returnPathname = new URL(request.url).searchParams.get('returnPathname');
        const url = await getSignInUrl(returnPathname ? { data: { returnPathname } } : undefined);
        return new Response(null, {
          status: 307,
          headers: { Location: url },
        });
      },
    },
  },
});
```

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

### useAuth

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

Access authentication state and methods in client components. Requires the AuthKitProvider wrapper.

```APIDOC
## useAuth

### Description
Access authentication state and methods in client components.

### Parameters
- **ensureSignedIn** (boolean) - Optional - If true, automatically triggers sign-in flow for unauthenticated users.

### Returns
- **user** (object) - Current user or null
- **loading** (boolean) - Loading state
- **sessionId** (string) - Current session ID
- **organizationId** (string) - Current organization ID
- **role/roles** (string/array) - User roles
- **permissions** (array) - User permissions
- **entitlements** (array) - User entitlements
- **featureFlags** (array) - Enabled feature flags
- **impersonator** (object) - Impersonator details
- **getAuth** (function) - Refresh auth state
- **refreshAuth** (function) - Refresh session with optional org switch
- **signOut** (function) - Sign out
- **switchToOrganization** (function) - Switch organizations
```

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

### Implement basic authentication usage

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/02-client-hooks.md

Standard implementation of useAuth to access user state and perform basic actions like refreshing or signing out.

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

export function Dashboard() {
  const { user, loading, refreshAuth, signOut } = useAuth();

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

  return (
    <div>
      <h1>Hello {user.firstName}</h1>
      <button onClick={() => refreshAuth()}>Refresh</button>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}
```

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

### Validate AuthKit Configuration

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/09-errors.md

Use the SDK function to validate that required environment variables are correctly set.

```bash
# Check .env file has all required vars
cat .env | grep WORKOS_

# Validate with SDK function
import { validateConfig } from '@workos/authkit-tanstack-react-start';
await validateConfig();
```

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

### Initial Auth State Loading

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Pre-loads authentication state in the root route loader to prevent UI flicker during initial load.

```typescript
export const Route = createRootRoute({
  loader: async () => {
    const initialAuth = await getAuthAction();
    return { initialAuth };
  },
  component: ({ loaderData }) => (
    <AuthKitProvider initialAuth={loaderData.initialAuth}>
      <App />
    </AuthKitProvider>
  ),
});
```

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

### Sign out with return URL

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/02-client-hooks.md

Configures the sign-out process to redirect the user to a specific path upon completion.

```typescript
const { signOut } = useAuth();

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

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

### Validate Configuration

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Run this function during application initialization to ensure all required environment variables are present and valid.

```typescript
import { validateConfig } from '@workos/authkit-tanstack-react-start';

await validateConfig();
// Throws if any required env var is missing or invalid
```

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

### Import Advanced Context Utilities

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

Use these imports for accessing AuthKit context and middleware configurations.

```typescript
import {
  getAuthKitContext,
  getAuthkit,
  authkitMiddleware,
} from '@workos/authkit-tanstack-react-start';
```

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

### getAuth(options?: { ensureSignedIn?: boolean })

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Manually refetch the current authentication state.

```APIDOC
## getAuth(options?: { ensureSignedIn?: boolean })

### Description
Manually refetch authentication state. Useful for refreshing permissions after backend changes.

### Parameters
- **ensureSignedIn** (boolean) - Optional - If true and no user is present, re-tries the fetch.

### Returns
- Promise<void>
```

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

### Generate sign-in URL with getSignInUrl

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

Creates a URL for redirecting users to the AuthKit sign-in page.

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

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

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

### useAuth() Return Structure

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Provides the current user session, organization context, and authentication management methods.

```typescript
{
  user: User | null              // Current user
  sessionId?: string             // Session ID
  organizationId?: string        // Active org
  role?: string                  // User role
  roles?: string[]               // All roles
  permissions?: string[]         // Permissions
  entitlements?: string[]        // Entitlements
  featureFlags?: string[]        // Feature flags
  impersonator?: Impersonator    // If impersonated
  loading: boolean               // Data loading
  getAuth: () => Promise<void>   // Manual fetch
  refreshAuth: (opts?) => Promise<void | { error: string }>  // Refresh session
  signOut: (opts?) => Promise<void>  // Sign out
  switchToOrganization: (id: string) => Promise<void | { error: string }>
}
```

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

### Configure return path after authentication

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/05-callback-handler.md

Specify a custom redirect path to navigate to after a successful authentication.

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

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

### Use signOut Method

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Sign out the current user, triggering a full page redirect.

```typescript
const { signOut } = useAuth();

await signOut();
// or
await signOut({ returnTo: '/' });
```

```typescript
function SignOutButton() {
  const { signOut } = useAuth();

  return (
    <button onClick={() => signOut({ returnTo: '/' })}>
      Sign Out
    </button>
  );
}
```

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

### HandleCallbackOptions

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/06-types-reference.md

Configuration options for the handleCallbackRoute function.

```APIDOC
## HandleCallbackOptions

### Description
Options for configuring the behavior of the callback route handler.

### Properties
- **returnPathname** (string | undefined) - Path to redirect to after success.
- **onSuccess** (function | undefined) - Callback function executed on successful authentication.
- **onError** (function | undefined) - Custom error handler function.
- **errorRedirectUrl** (string | undefined) - URL to redirect to when an error occurs.
```

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

### Configure WORKOS_REDIRECT_URI

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Set the OAuth callback URL that matches the sign-in endpoint registered in the WorkOS dashboard.

```bash
WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback
WORKOS_REDIRECT_URI=https://app.example.com/api/auth/callback
```

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

### useAuth()

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Provides access to the current user session, organization context, and authentication management methods.

```APIDOC
## useAuth()

### Description
Returns the current authentication state and methods to manage the user session.

### Return Values
- **user** (User | null) - Current user object
- **sessionId** (string) - Session ID
- **organizationId** (string) - Active organization ID
- **role** (string) - Current user role
- **roles** (string[]) - All user roles
- **permissions** (string[]) - User permissions
- **entitlements** (string[]) - User entitlements
- **featureFlags** (string[]) - Enabled feature flags
- **impersonator** (Impersonator) - Impersonation details if active
- **loading** (boolean) - Loading state
- **getAuth** (Function) - Manual fetch of auth state
- **refreshAuth** (Function) - Refresh session
- **signOut** (Function) - Sign out the user
- **switchToOrganization** (Function) - Switch active organization
```

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

### signOut(options?: { returnTo?: string })

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Sign out the current user and optionally redirect to a specific URL.

```APIDOC
## signOut(options?: { returnTo?: string })

### Description
Sign out the current user. This method triggers a full page redirect.

### Parameters
- **returnTo** (string) - Optional - URL to redirect to after sign-out.

### Returns
- Promise (never resolves, triggers redirect)
```

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

### Required Environment Variables

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/11-quick-reference.md

Essential configuration variables that must be set in your environment for AuthKit to function.

```bash
WORKOS_CLIENT_ID=client_...              # From WorkOS dashboard
WORKOS_API_KEY=sk_test_...               # From WorkOS dashboard
WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback  # Must match dashboard
WORKOS_COOKIE_PASSWORD=...               # Min 32 characters (use: openssl rand -base64 24)
```

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

### Create Sign-In Button Component

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

A client-side button component that dynamically imports the sign-in URL generator and redirects the user.

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

export function SignInButton() {
  const [loading, setLoading] = React.useState(false);

  const handleClick = async () => {
    setLoading(true);
    try {
      const { getSignInUrl } = await import('@workos/authkit-tanstack-react-start');
      const url = await getSignInUrl();
      window.location.href = url;
    } catch (error) {
      console.error('Failed to get sign-in URL:', error);
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? 'Loading...' : 'Sign In'}
    </button>
  );
}
```

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

### Add AuthKit Provider

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

Wrap the application root with AuthKitProvider to enable client-side hooks like useAuth().

```typescript
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>
  );
}
```

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

### Implementing Server Actions with Auth

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/00-index.md

Access authentication context within server functions using getAuthKitContext. Throws an error if the user is not authenticated.

```typescript
export const myAction = createServerFn().handler(async () => {
  const { auth } = getAuthKitContext();
  const { user, claims } = auth();

  if (!user) throw new Error('Not authenticated');
  return { email: user.email, org: claims?.org_id };
});
```

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

### Configure Package for Tree-Shaking

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

The package configuration ensures that unused exports are excluded from the final bundle.

```json
{
  "type": "module",
  "sideEffects": false
}
```

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

### Import Client-Side Auth Hooks

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/10-module-exports.md

Use these imports for client-side authentication state and user information retrieval.

```typescript
import {
  AuthKitProvider,
  useAuth,
  useAccessToken,
  useTokenClaims,
  useRecentAuth,
} from '@workos/authkit-tanstack-react-start/client';
```

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

### switchToOrganization(organizationId: string)

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Switch the active session to a different organization.

```APIDOC
## switchToOrganization(organizationId: string)

### Description
Switch to a different organization.

### Parameters
- **organizationId** (string) - Required - Target organization ID.

### Returns
- Promise<void | { error: string }>
```

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

### Configure WORKOS_COOKIE_SAMESITE

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Set the SameSite attribute for CSRF protection.

```bash
WORKOS_COOKIE_SAMESITE=strict      # Maximum security
WORKOS_COOKIE_SAMESITE=lax         # Default, good balance
WORKOS_COOKIE_SAMESITE=none        # For cross-origin requests (requires HTTPS)
```

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

### Access Request Headers

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Demonstrates accessing the original request object and authentication state simultaneously.

```typescript
const { request, auth } = getAuthKitContext();
const userAgent = request.headers.get('user-agent');
const { user } = auth();
```

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

### Create Protected Route Component

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

A component that ensures the user is signed in before rendering protected content.

```typescript
export function ProtectedPage() {
  const { user, loading } = useAuth({ ensureSignedIn: true });

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

  // user is guaranteed to be non-null here
  return (
    <div>
      <h1>Welcome, {user.firstName}</h1>
      <p>Email: {user.email}</p>
    </div>
  );
}
```

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

### AuthKitProvider

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/07-configuration.md

Configuration props for the AuthKitProvider component to manage session expiration and initial authentication state.

```APIDOC
## AuthKitProvider

### Description
Provides authentication context to the application. Supports custom session expiration handling and pre-loading of authentication state.

### Props
- **onSessionExpired** (false | () => void | undefined) - Optional - Defines behavior when a session expires. Defaults to reloading the page. Set to `false` to disable checks, or provide a callback function.
- **initialAuth** (ClientUserInfo | NoUserInfo | undefined) - Optional - Pre-loads authentication state from a route loader to prevent loading flicker.
```

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

### switchToOrganizationAction

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/03-server-actions.md

Switches the current user context to a different organization and refreshes claims.

```APIDOC
## switchToOrganizationAction

### Description
Switches to a different organization and refreshes user claims. This action is used to update the organization context for the current session.

### Signature
`switchToOrganizationAction(data: { organizationId: string }) => Promise<Omit<UserInfo, 'accessToken'> | NoUserInfo>`

### Parameters
- **organizationId** (string) - Required - Target organization ID

### Example
```typescript
import { switchToOrganizationAction } from '@workos/authkit-tanstack-react-start';

const auth = await switchToOrganizationAction({ organizationId: 'org_456' });
if ('user' in auth && auth.user) {
  console.log(`Switched to ${auth.organizationId}, role: ${auth.role}`);
}
```
```

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

### getAuthkit()

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/04-context-middleware.md

Initializes or retrieves the cached AuthKit service instance for session management. This is typically used for advanced manual callback handling.

```APIDOC
## getAuthkit()

### Description
Gets or initializes the AuthKit service instance. This service provides methods for session management and is lazily initialized on the first call.

### Signature
`export function getAuthkit(): Promise<AuthService<Request, Response>>`

### Return Type
`Promise<AuthService>` — A framework-agnostic service for session management.

### AuthService Methods
- `handleCallback(request, response, options)` — Processes an OAuth callback.
- `refreshSession(data, options)` — Refreshes a session with optional organization context.
- `clearPendingVerifier(response, options)` — Clears the PKCE verifier cookie.

### Behavior
- Lazily initializes on the first call and caches the instance.
- Throws an error if required environment variables (WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_COOKIE_PASSWORD) are missing.
```

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

### Switch Organizations

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

Update the active organization context for multi-org users.

```typescript
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.
```

```typescript
const { switchToOrganization, organizationId } = useAuth();

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

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

### Use getAuth Method

Source: https://github.com/workos/authkit-tanstack-start/blob/main/_autodocs/08-components.md

Manually refetch authentication state using the getAuth method.

```typescript
const { getAuth } = useAuth();

await getAuth();
// or
await getAuth({ ensureSignedIn: true });
```

```typescript
const { getAuth } = useAuth();

const handlePermissionChange = async () => {
  // After permissions change on backend
  await getAuth(); // Refresh to get new permissions
};
```
Tokens:
Raw