AuthKit React Router

https://github.com/workos/authkit-react-router
Admin
The AuthKit library for React Router 7+ provides convenient helpers for authentication and session...
Tokens:10,536
Snippets:45
Trust Score:10
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install AuthKit React Router with npm

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

Shows how to install the AuthKit React Router package using npm. This is a common setup for Node.js projects.

```bash
npm i @workos-inc/authkit-react-router
```

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

### Install AuthKit React Router with yarn

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

Shows how to install the AuthKit React Router package using yarn.  This is another common package manager option.

```bash
yarn add @workos-inc/authkit-react-router
```

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

### Access Authentication Data with AuthKit in React Router

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

This example shows how to use `authkitLoader` to access user data (user, signInUrl, signUpUrl) within your React Router components. It demonstrates fetching data using `useLoaderData` and displaying user information.

```TypeScript
import { type LoaderFunctionArgs, useLoaderData } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) => authkitLoader(args);

export function App() {
  const { user, signInUrl, signUpUrl } = useLoaderData<typeof loader>();

  return (
    <div>
      <p>Welcome back {user?.firstName && `, ${user?.firstName}`}</p>
    </div>
  );
}
```

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

### Authentication Implementation Patterns

Source: https://context7.com/workos/authkit-react-router/llms.txt

Complete authentication workflow implementation for React Router using WorkOS AuthKit. Includes session refresh lifecycle hooks with audit logging and error handling, sign-in/sign-up URL generation, form-based and custom redirect sign-out flows, and low-level withAuth integration for custom authentication patterns. All examples demonstrate TypeScript integration with error handling, audit trails, and session management.

```typescript
// Session refresh lifecycle hooks
// app/routes/root.tsx
import { type LoaderFunctionArgs } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';
import { logAuditEvent } from '~/lib/audit';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, {
    debug: true, // Enable debug logging
    onSessionRefreshSuccess: async ({ user, accessToken, organizationId, impersonator }) => {
      // Log successful token refresh for audit trail
      await logAuditEvent({
        type: 'session_refreshed',
        userId: user.id,
        email: user.email,
        organizationId,
        impersonatedBy: impersonator?.email,
        timestamp: new Date(),
      });

      console.log(`Session refreshed for ${user.email}`);
    },
    onSessionRefreshError: async ({ error, request, sessionData }) => {
      // Log refresh failures
      console.error('Session refresh failed:', error);

      // Optional: Handle specific error cases
      const errorCause = error instanceof Error ? error.cause : null;

      if (errorCause && typeof errorCause === 'object' && 'error' in errorCause) {
        if (errorCause.error === 'sso_required') {
          console.log('SSO re-authentication required');
        } else if (errorCause.error === 'mfa_enrollment') {
          console.log('MFA enrollment required');
        }
      }

      // Clear any cached data
      sessionData.unset('cached_user_data');
    },
  });
```

```typescript
// Generate authentication URLs
// app/routes/_index.tsx
import { type LoaderFunctionArgs, Link, useLoaderData, data } from 'react-router';
import { authkitLoader, getSignInUrl, getSignUpUrl } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ request }) => {
    const url = new URL(request.url);
    const returnPath = url.searchParams.get('return') || '/dashboard';

    return data({
      signInUrl: await getSignInUrl(returnPath),
      signUpUrl: await getSignUpUrl(returnPath),
    });
  });

export default function HomePage() {
  const { user, signInUrl, signUpUrl } = useLoaderData<typeof loader>();

  if (!user) {
    return (
      <div>
        <h1>Welcome to Our App</h1>
        <Link to={signInUrl}>Sign In</Link>
        <Link to={signUpUrl}>Sign Up</Link>
      </div>
    );
  }

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

```typescript
// Sign out with form submission
// app/routes/settings.tsx
import { type ActionFunctionArgs, type LoaderFunctionArgs, Form, useLoaderData } from 'react-router';
import { authkitLoader, signOut } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, { ensureSignedIn: true });

export async function action({ request }: ActionFunctionArgs) {
  // Sign out and redirect to homepage
  return await signOut(request);
}

export default function SettingsPage() {
  const { user } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>Settings for {user.email}</h1>
      <Form method="post">
        <button type="submit">Sign Out</button>
      </Form>
    </div>
  );
}
```

```typescript
// Sign out with custom redirect
// app/routes/admin/logout.tsx
import { type ActionFunctionArgs } from 'react-router';
import { signOut } from '@workos-inc/authkit-react-router';

export async function action({ request }: ActionFunctionArgs) {
  // Sign out and redirect to custom logout page
  return await signOut(request, {
    returnTo: 'https://example.com/goodbye'
  });
}
```

```typescript
// Use withAuth for custom authentication flows
// app/routes/api/user-info.tsx
import { type LoaderFunctionArgs, data, redirect } from 'react-router';
import { withAuth, getSignInUrl } from '@workos-inc/authkit-react-router';

export const loader = async (args: LoaderFunctionArgs) => {
  const auth = await withAuth(args);

  // Manually handle unauthenticated users
  if (!auth.user) {
    throw redirect(await getSignInUrl());
  }

  // Access token is directly available (not behind a function)
  const { user, accessToken, sessionId, organizationId, permissions } = auth;

  // Use for server-side operations
  const externalData = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Session-ID': sessionId,
    },
  });

  return data({
    user: {
      id: user.id,
      email: user.email,
      name: `${user.firstName} ${user.lastName}`,
    },
    organizationId,
    permissions,
    externalData: await externalData.json(),
    // WARNING: Only expose accessToken if client needs it
    // accessToken, // ⚠️ Uncomment only if necessary
  });
};
```

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

### Feature Flag Gating with React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

This example shows how to gate features using feature flags provided by WorkOS AuthKit. It checks if the user has access to specific beta features or advanced functionalities based on the presence of flags like 'new_editor_beta' or 'advanced_features' in their authentication context.

```typescript
// app/routes/beta/new-editor.tsx
import { type LoaderFunctionArgs, data, redirect } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth }) => {
    if (!auth.user) {
      throw redirect('/sign-in');
    }

    // Check feature flag access
    const hasNewEditorAccess = auth.featureFlags?.includes('new_editor_beta');
    const hasAdvancedFeatures = auth.featureFlags?.includes('advanced_features');

    if (!hasNewEditorAccess) {
      return data(
        { error: 'Beta access required' },
        { status: 403 }
      );
    }

    return data({
      user: auth.user,
      features: {
        newEditor: true,
        advancedTools: hasAdvancedFeatures,
        collaborationTools: auth.featureFlags?.includes('collaboration'),
      },
      allFeatureFlags: auth.featureFlags || [],
    });
  }, { ensureSignedIn: true });

```

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

### Use Access Token with `ensureSignedIn` in AuthKit React Router

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

Illustrates using the `ensureSignedIn: true` option with `authkitLoader`. This guarantees that `getAccessToken()` will return a valid token, simplifying API calls within the loader. The example fetches protected data using the guaranteed access token.

```tsx
export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth, getAccessToken }) => {
    // With ensureSignedIn: true, the user is guaranteed to be authenticated
    const accessToken = getAccessToken();
    
    // Use the token for your API calls
    const data = await fetchProtectedData(accessToken);
    
    return { data };
  }, { ensureSignedIn: true });
```

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

### Role-Based Access Control (RBAC) with React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

This example demonstrates how to implement role-based access control (RBAC) for routes using `authkitLoader`. It checks if the authenticated user has the 'admin' role or is in the 'admin' or 'moderator' roles list before granting access to protected resources.

```typescript
// app/routes/admin/users.tsx
import { type LoaderFunctionArgs, data, redirect } from 'react-router';
import { authkitLoader, getSignInUrl } from '@workos-inc/authkit-react-router';
import { db } from '~/lib/database';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth }) => {
    if (!auth.user) {
      throw redirect(await getSignInUrl());
    }

    // Check for admin or moderator role
    const hasAccess = 
      auth.role === 'admin' ||
      auth.roles?.some(role => ['admin', 'moderator'].includes(role));

    if (!hasAccess) {
      return data(
        { error: 'Insufficient permissions' },
        { status: 403 }
      );
    }

    const users = await db.users.findAll();

    return data({
      users,
      currentUserRole: auth.role,
      allRoles: auth.roles || [],
    });
  });

```

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

### Get Access Token in Loader with AuthKit React Router

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

Demonstrates how to retrieve an access token within a React Router loader using the `authkitLoader` function. This is useful for making authenticated server-side API calls. It includes handling for unauthenticated users and making fetch requests with the token.

```tsx
import { data, type LoaderFunctionArgs } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth, getAccessToken }) => {
    if (!auth.user) {
      // Not signed in - getAccessToken() would return null
      return data({ data: null });
    }

    // Explicitly call the function to get the access token
    const accessToken = getAccessToken();
    
    const serviceData = await fetch('/api/path', {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    });

    return data({
      data: await serviceData.json(),
    });
  });
```

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

### Configure AuthKit with a Custom Environment Source (TypeScript)

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

Demonstrates using a custom environment source, suitable for non-standard environments like Deno or Edge functions. This feature is still under testing.

```typescript
import { configure } from '@workos-inc/authkit-react-router';

configure(key => Deno.env.get(key));
// Or combine with explicit values
configure(
  { clientId: 'client_1234567890' },
  key => Deno.env.get(key)
);
```

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

### Configure AuthKit with Environment Variables

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

Demonstrates configuring AuthKit using environment variables, which is a simple and convenient approach. You must retrieve the Client ID, API Key, and Redirect URI from the WorkOS dashboard.

```bash
WORKOS_CLIENT_ID="client_..." # retrieved from the WorkOS dashboard
WORKOS_API_KEY="sk_test_..." # retrieved from the WorkOS dashboard
WORKOS_REDIRECT_URI="http://localhost:5173/callback" # configured in the WorkOS dashboard
WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
```

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

### Configure AuthKit Programmatically (TypeScript)

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

Shows how to configure AuthKit programmatically using the `configure` function. This allows for more flexibility in customization.

```typescript
import { configure } from '@workos-inc/authkit-react-router';
// In your root or entry file
configure({
  clientId: 'client_1234567890',
  apiKey: 'sk_test_1234567890',
  redirectUri: 'http://localhost:5173/callback',
  cookiePassword: 'your-secure-cookie-password',
  // Optional settings
  cookieName: 'my-custom-cookie-name',
  apiHttps: true,
  cookieMaxAge: 60 * 60 * 24 * 30, // 30 days
});
```

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

### Configure AuthKit with Environment Variables

Source: https://context7.com/workos/authkit-react-router/llms.txt

Set up AuthKit authentication by defining essential configuration parameters using environment variables. These variables include client ID, API key, redirect URI, and a secure cookie password for session management.

```bash
WORKOS_CLIENT_ID="client_1234567890"
WORKOS_API_KEY="sk_test_1234567890"
WORKOS_REDIRECT_URI="http://localhost:5173/callback"
WORKOS_COOKIE_PASSWORD="your-secure-password-at-least-32-characters-long"
```

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

### Signing Out with AuthKit

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

Shows how to use the `signOut` method to sign out a user and redirect them to a specified URL (configured in the WorkOS dashboard).

```TypeScript
export async function action({ request }: ActionFunctionArgs) {
  return await signOut(request, { returnTo: 'https://example.com' });
}
```

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

### React Router Callback Route with AuthKit

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

This snippet demonstrates setting up a callback route in a React Router application using `@workos-inc/authkit-react-router`. It redirects users back to this route after successful authentication. Ensure the route matches your WORKOS_REDIRECT_URI and redirect URI in WorkOS dashboard.

```TypeScript
import { authLoader } from '@workos-inc/authkit-react-router';

export const loader = authLoader();
```

```TypeScript
export const loader = authLoader({ returnPathname: '/dashboard' });
```

```TypeScript
export const loader = authLoader({ onSuccess: async ({ oauthTokens }) => { await saveToDatabase(oauthTokens); }, });
```

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

### Custom Loader with Authentication Context (React Router)

Source: https://context7.com/workos/authkit-react-router/llms.txt

Illustrates a custom loader that composes the authentication context from authkitLoader with async data fetching from a local database. Returns a combined data object including profile and posts. Ideal for pages that need both user details and application-specific data.

```TypeScript
// app/routes/profile.tsx
import { type LoaderFunctionArgs, useLoaderData, data } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';
import { db } from '~/lib/database';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ request, auth, getAccessToken }) => {
    if (!auth.user) {
      return data({ profile: null, posts: [] });
    }

    // Fetch user profile and posts from database
    const [profile, posts] = await Promise.all([
      db.profiles.findByUserId(auth.user.id),
      db.posts.findByUserId(auth.user.id),
    ]);

    return data({ profile, posts });
  });

export default function ProfilePage() {
  const { user, profile, posts } = useLoaderData<typeof loader>();

  if (!user) {
    return <div>Please sign in to view your profile</div>;
  }

  return (
    <div>
      <h1>{profile?.displayName || user.firstName}</h1>
      <h2>Your Posts ({posts.length})</h2>
      {posts.map(post => (
        <article key={post.id}>
          <h3>{post.title}</h3>
          <p>{post.content}</p>
        </article>
      ))}
    </div>
  );
}

```

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

### Expose Access Token to Client-Side with AuthKit React Router

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

Shows how to explicitly return an access token from a loader to make it available to client-side code. This should only be done when absolutely necessary due to security risks. It also shows how to use the `ensureSignedIn` option.

```tsx
export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth, getAccessToken }) => {
    const accessToken = getAccessToken();
    
    return {
      // Only expose to client if absolutely necessary
      accessToken,
      userData: await fetchUserData(accessToken)
    };
  }, { ensureSignedIn: true });
```

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

### Access Authentication Data with AuthKit and Custom Loader in React Router

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

Illustrates using `authkitLoader` with a custom loader function to fetch additional data, like sign-in and sign-up URLs.

```TypeScript
import type { ActionFunctionArgs, LoaderFunctionArgs, data } from 'react-router';
import { getSignInUrl, getSignUpUrl, signOut, authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ request, auth }) => {
    return data({
      signInUrl: await getSignInUrl(),
      signUpUrl: await getSignUpUrl(),
    });
  });

export async function action({ request }: ActionFunctionArgs) {
  return await signOut(request);
}

export default function HomePage() {
  const { user, signInUrl, signUpUrl } = useLoaderData<typeof loader>();

  if (!user) {
    return (
      <>{
        <Link to={signInUrl}>Log in</Link>
        <br />
        <Link to={signUpUrl}>Sign Up</Link>
      </>
    );
  }

  return (
    <Form method="post">
      <p>Welcome back {user?.firstName && `, ${user?.firstName}`}</p>
      <button type="submit">Sign out</button>
    </Form>
  );
}
```

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

### Configure AuthKit with Custom Environment Sources (Deno/Edge)

Source: https://context7.com/workos/authkit-react-router/llms.txt

Adapt AuthKit configuration for serverless or non-Node.js environments like Deno or Edge runtimes by providing custom functions to read environment variables. This enables flexibility in how configuration values are sourced.

```typescript
import { configure } from '@workos-inc/authkit-react-router';

// Use Deno environment variables
configure(key => Deno.env.get(key));

// Combine explicit values with custom source
configure(
  {
    clientId: 'client_1234567890',
    cookiePassword: 'your-secure-cookie-password-at-least-32-chars'
  },
  key => Deno.env.get(key)
);

// Custom environment source for Edge functions
configure(key => {
  const env = process.env as Record<string, string>;
  return env[key];
});
```

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

### Require Authentication with AuthKit

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

This snippet demonstrates how to use the `ensureSignedIn` option to redirect users to authentication if they are not already signed in.

```TypeScript
export const loader = (args: LoaderFunctionArgs) => authkitLoader(args, { ensureSignedIn: true });
```

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

### Set Up Basic OAuth Callback Handler in React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

Implement a basic OAuth callback route handler in your React Router application using the `authLoader` utility. This handler is responsible for processing the callback from the OAuth provider after user authentication.

```typescript
// app/routes/callback.ts
import { authLoader } from '@workos-inc/authkit-react-router';

// Basic callback handler
export const loader = authLoader();
```

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

### Creating Reusable Custom Session Storage Configuration

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

Shows a pattern for creating a reusable function that returns a custom session storage configuration. This promotes code reuse and consistency across different routes in your application, especially when integrating with AuthKit.

```typescript
// app/lib/session.ts
export function getAuthStorage() {
  const storage = createCookieSessionStorage({/* config */});
  return { storage, cookie: { name: "my-custom-session" } };
}

// Then in your routes
import { getAuthStorage } from "~/lib/session";
export const loader = (args) => authkitLoader(args, {
  ...getAuthStorage(),
  // Other options...
});
```

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

### Basic Authentication with Optional User (React Router)

Source: https://context7.com/workos/authkit-react-router/llms.txt

Shows how to use the authkitLoader as a React Router loader, returning the authenticated user, session, organization, role, and permissions. It is intended for public pages where the user may be absent, and it does not enforce authentication. Dependencies: @workos-inc/authkit-react-router, react-router.

```TypeScript
// app/routes/_index.tsx
import { type LoaderFunctionArgs, useLoaderData } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) => authkitLoader(args);

export default function HomePage() {
  const { user, sessionId, organizationId, role, permissions } = useLoaderData<typeof loader>();

  if (!user) {
    return <div>Please sign in to continue</div>;
  }

  return (
    <div>
      <h1>Welcome {user.firstName} {user.lastName}</h1>
      <p>Email: {user.email}</p>
      <p>Session ID: {sessionId}</p>
      {organizationId && <p>Organization: {organizationId}</p>}
      {role && <p>Role: {role}</p>}
      {permissions && permissions.length > 0 && (
        <div>
          <h2>Permissions:</h2>
          <ul>
            {permissions.map(permission => (
              <li key={permission}>{permission}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

```

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

### Switch Organization Context - TypeScript React Router Action

Source: https://context7.com/workos/authkit-react-router/llms.txt

Server-side action to switch user organization context. Accepts organizationId and optional returnTo parameter. Validates input and calls switchToOrganization helper. Dependencies: @workos-inc/authkit-react-router, react-router. Inputs: FormData with organizationId, returnTo. Outputs: Redirect response or error data.

```typescript
// app/routes/organization/switch.tsx
import { type ActionFunctionArgs, data } from 'react-router';
import { switchToOrganization } from '@workos-inc/authkit-react-router';

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const organizationId = formData.get('organizationId') as string;
  const returnTo = formData.get('returnTo') as string | undefined;

  if (!organizationId) {
    return data({ error: 'Organization ID required' }, { status: 400 });
  }

  try {
    // Switch organization and optionally redirect
    const result = await switchToOrganization(
      request,
      organizationId,
      { returnTo: returnTo || '/dashboard' }
    );

    return result;
  } catch (error) {
    console.error('Failed to switch organization:', error);
    return data(
      { error: 'Failed to switch organization' },
      { status: 500 }
    );
  }
}
```

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

### Enable Debugging with `authkitLoader` in AuthKit React Router

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

Shows how to enable debug logs for `authkitLoader` by passing the `debug: true` option. This can be done when providing only options or when providing both loader function and options.

```ts
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) => authkitLoader(args, { debug: true });
```

```ts
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(
    args,
    async ({ auth }) => {
      return json({ foo: 'bar' });
    },
    { debug: true },
  );
```

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

### Implementing Custom Memory Session Storage with AuthKit

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

Demonstrates how to replace the default cookie storage with a memory-based session storage implementation using `createMemorySessionStorage` from `@react-router/node`. This custom storage can be passed to both `authkitLoader` and `authLoader` for consistent session management.

```typescript
import { createMemorySessionStorage } from "@react-router/node";
import { authkitLoader, authLoader } from "@workos-inc/authkit-react-router";

// Create memory-based session storage
const memoryStorage = createMemorySessionStorage({
  cookie: {
    name: "auth-session",
    secrets: ["test-secret"],
    sameSite: "lax",
    path: "/",
    httpOnly: true,
    secure: false, // Use false for testing
    maxAge: 60 * 60 * 24 // 1 day
  }
});

// In your root loader
export const loader = (args) => authkitLoader(args, {
  storage: memoryStorage,
  cookie: { name: "auth-session" }
});

// In your callback route
export const loader = authLoader({
  storage: memoryStorage,
  cookie: { name: "auth-session" }
});
```

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

### Access WorkOS SDK in React Router Loader

Source: https://context7.com/workos/authkit-react-router/llms.txt

Demonstrates direct usage of WorkOS SDK within a React Router loader function to fetch organization membership data. Requires authenticated user with organization context and proper WorkOS API credentials configured. Handles errors gracefully and returns structured organization data with member information.

```typescript
// app/routes/api/organization-members.tsx
import { type LoaderFunctionArgs, data } from 'react-router';
import { authkitLoader, getWorkOS } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth }) => {
    if (!auth.user || !auth.organizationId) {
      return data({ error: 'Organization context required' }, { status: 400 });
    }

    const workos = getWorkOS();

    try {
      // List organization members using WorkOS SDK
      const { data: members } = await workos.userManagement.listOrganizationMemberships({
        organizationId: auth.organizationId,
      });

      // Get organization details
      const organization = await workos.organizations.getOrganization(auth.organizationId);

      return data({
        organization: {
          id: organization.id,
          name: organization.name,
          domains: organization.domains,
        },
        members: members.map(member => ({
          userId: member.userId,
          role: member.role,
          status: member.status,
        })),
        totalMembers: members.length,
      });
    } catch (error) {
      console.error('Failed to fetch organization data:', error);
      return data({ error: 'Failed to fetch organization data' }, { status: 500 });
    }
  }, { ensureSignedIn: true });
```

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

### Organization Switcher Component - TypeScript React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

Dashboard component with organization switcher functionality. Uses authkitLoader to fetch user organizations and displays conditional switcher when multiple orgs available. Dependencies: @workos-inc/authkit-react-router, react-router, database. Inputs: User authentication context. Outputs: JSX with user data and organization switcher form.

```typescript
// app/routes/dashboard.tsx
import { type LoaderFunctionArgs, Form, useLoaderData, data } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';
import { db } from '~/lib/database';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth }) => {
    if (!auth.user) {
      return data({ organizations: [] });
    }

    // Fetch user's organizations
    const organizations = await db.organizations.findByUserId(auth.user.id);

    return data({ organizations });
  }, { ensureSignedIn: true });

export default function DashboardPage() {
  const { user, organizationId, organizations } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Current Organization: {organizationId || 'None'}</p>

      {organizations.length > 1 && (
        <Form method="post" action="/organization/switch">
          <label>
            Switch Organization:
            <select name="organizationId" defaultValue={organizationId || ''}>
              {organizations.map(org => (
                <option key={org.id} value={org.id}>
                  {org.name}
                </option>
              ))}
            </select>
          </label>
          <input type="hidden" name="returnTo" value="/dashboard" />
          <button type="submit">Switch</button>
        </Form>
      )}
    </div>
  );
}
```

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

### Check User Entitlements in React Router Loader

Source: https://context7.com/workos/authkit-react-router/llms.txt

Implements entitlement checking using authkitLoader to determine user access to premium features. Returns feature flags based on user entitlements and displays appropriate UI components conditionally. Requires authenticated user context and entitlement configuration in WorkOS.

```typescript
// app/routes/premium/features.tsx
import { type LoaderFunctionArgs, data, useLoaderData } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth }) => {
    if (!auth.user) {
      return data({ isPremium: false, features: [] });
    }

    const entitlements = auth.entitlements || [];

    // Check for specific entitlements
    const hasEntitlement = (name: string) => entitlements.includes(name);

    return data({
      isPremium: hasEntitlement('premium_subscription'),
      features: {
        unlimitedStorage: hasEntitlement('unlimited_storage'),
        prioritySupport: hasEntitlement('priority_support'),
        advancedAnalytics: hasEntitlement('advanced_analytics'),
        apiAccess: hasEntitlement('api_access'),
      },
      allEntitlements: entitlements,
    });
  });

export default function PremiumFeaturesPage() {
  const { user, isPremium, features, allEntitlements } = useLoaderData<typeof loader>();

  if (!user) {
    return <div>Sign in to access premium features</div>;
  }

  if (!isPremium) {
    return <div>Upgrade to premium to access these features</div>;
  }

  return (
    <div>
      <h1>Premium Features</h1>
      <ul>
        {features.unlimitedStorage && <li>Unlimited Storage</li>}
        {features.prioritySupport && <li>Priority Support</li>}
        {features.advancedAnalytics && <li>Advanced Analytics</li>}
        {features.apiAccess && <li>API Access</li>}
      </ul>
      <details>
        <summary>All Entitlements</summary>
        <pre>{JSON.stringify(allEntitlements, null, 2)}</pre>
      </details>
    </div>
  );
}
```

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

### Handle OAuth Token Persistence on Callback Success

Source: https://context7.com/workos/authkit-react-router/llms.txt

Extend the OAuth callback handler to persist OAuth tokens to a database upon successful authentication. The `onSuccess` callback within `authLoader` allows for custom logic, such as saving tokens for subsequent API interactions and logging authentication events.

```typescript
// app/routes/callback.ts
import { authLoader } from '@workos-inc/authkit-react-router';
import { saveOAuthTokens } from '~/lib/database';

export const loader = authLoader({
  returnPathname: '/dashboard',
  onSuccess: async ({ oauthTokens, user, accessToken, refreshToken, impersonator }) => {
    // Persist OAuth tokens to database for API integrations
    if (oauthTokens) {
      await saveOAuthTokens({
        userId: user.id,
        accessToken: oauthTokens.accessToken,
        refreshToken: oauthTokens.refreshToken,
        expiresAt: new Date(Date.now() + oauthTokens.expiresIn * 1000),
        provider: oauthTokens.provider,
      });
    }

    // Log successful authentication
    console.log(`User ${user.email} authenticated successfully`);
    if (impersonator) {
      console.log(`Impersonated by ${impersonator.email}: ${impersonator.reason}`);
    }
  },
});
```

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

### Access Token Usage with External APIs (React Router)

Source: https://context7.com/workos/authkit-react-router/llms.txt

Demonstrates using the getAccessToken function from the authkitLoader callback to obtain an OAuth token and call an external API. Handles authentication requirements and errors, returning a response or an error status. Useful for integrating external services that require bearer token authentication.

```TypeScript
// app/routes/api-data.tsx
import { type LoaderFunctionArgs, data } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(
    args,
    async ({ auth, getAccessToken }) => {
      if (!auth.user) {
        return data({ error: 'Unauthorized' }, { status: 401 });
      }

      // Get access token to call external API
      const accessToken = getAccessToken();

      try {
        const response = await fetch('https://api.example.com/v1/user/data', {
          headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json',
          },
        });

        if (!response.ok) {
          throw new Error(`API error: ${response.status}`);
        }

        const apiData = await response.json();

        return data({
          user: auth.user,
          data: apiData,
          fetchedAt: new Date().toISOString(),
        });
      } catch (error) {
        console.error('Failed to fetch API data:', error);
        return data(
          { error: 'Failed to fetch data' },
          { status: 500 }
        );
      }
    },
    { ensureSignedIn: true }
  );

```

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

### Require Authentication for Protected Routes (React Router)

Source: https://context7.com/workos/authkit-react-router/llms.txt

Demonstrates protecting a route by passing the ensureSignedIn option to authkitLoader, which automatically redirects unauthenticated users to the sign-in page. Guarantees user data is present in the loader response. Useful for dashboard or authenticated pages.

```TypeScript
// app/routes/dashboard.tsx
import { type LoaderFunctionArgs, useLoaderData } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';

// Automatically redirects unauthenticated users to sign-in
export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, { ensureSignedIn: true });

export default function DashboardPage() {
  // User is guaranteed to be authenticated here
  const { user, sessionId, organizationId } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Hello, {user.firstName}!</p>
      <p>Session: {sessionId}</p>
    </div>
  );
}

```

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

### Custom Session Storage with Redis using React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

This snippet shows how to create a custom session storage using `react-router` and persist session data to Redis. It defines a `customSessionStorage` and a helper function `persistSessionToRedis` to store user session details like user ID, email, and access token with a time-to-live.

```typescript
// app/lib/session-storage.ts
import { createCookieSessionStorage } from 'react-router';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

export const customSessionStorage = createCookieSessionStorage({
  cookie: {
    name: 'authkit-session',
    secrets: [process.env.WORKOS_COOKIE_PASSWORD!],
    sameSite: 'lax',
    path: '/',
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 60 * 60 * 24 * 30, // 30 days
  },
});

// Helper to persist session data to Redis
export async function persistSessionToRedis(sessionId: string, data: any) {
  await redis.setex(
    `session:${sessionId}`,
    60 * 60 * 24 * 30, // 30 days TTL
    JSON.stringify(data)
  );
}

// app/routes/callback.ts
import { authLoader } from '@workos-inc/authkit-react-router';
import { customSessionStorage, persistSessionToRedis } from '~/lib/session-storage';

export const loader = authLoader({
  storage: customSessionStorage,
  cookie: { name: 'authkit-session' },
  onSuccess: async ({ user, accessToken, sessionId }) => {
    // Store session data in Redis
    await persistSessionToRedis(sessionId || user.id, {
      userId: user.id,
      email: user.email,
      accessToken,
      createdAt: new Date().toISOString(),
    });
  },
});

// app/routes/root.tsx
import { authkitLoader } from '@workos-inc/authkit-react-router';
import { customSessionStorage } from '~/lib/session-storage';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, {
    storage: customSessionStorage,
    cookie: { name: 'authkit-session' },
  });

```

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

### Custom Middleware with withAuth - TypeScript React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

Creates custom authentication middleware using withAuth helper. Validates user authentication and checks for admin role. Returns authenticated user context or redirects to sign-in. Dependencies: @workos-inc/authkit-react-router, react-router. Inputs: LoaderFunctionArgs. Outputs: User object with roles or error response.

```typescript
// app/lib/auth-middleware.ts
import { type LoaderFunctionArgs, redirect, data } from 'react-router';
import { withAuth, getSignInUrl } from '@workos-inc/authkit-react-router';

export async function requireAdmin(args: LoaderFunctionArgs) {
  const auth = await withAuth(args);

  if (!auth.user) {
    throw redirect(await getSignInUrl());
  }

  // Check if user has admin role
  const isAdmin = auth.roles?.includes('admin') || auth.role === 'admin';

  if (!isAdmin) {
    return data(
      { error: 'Forbidden: Admin access required' },
      { status: 403 }
    );
  }

  return auth;
}

// Usage in route
// app/routes/admin/dashboard.tsx
export const loader = async (args: LoaderFunctionArgs) => {
  const auth = await requireAdmin(args);

  if ('error' in auth) {
    throw new Response(auth.error, { status: 403 });
  }

  return data({ user: auth.user, isAdmin: true });
};
```

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

### Configure OAuth Callback with Custom Return Path

Source: https://context7.com/workos/authkit-react-router/llms.txt

Customize the user redirection path after a successful OAuth callback in React Router. The `authLoader` utility accepts a `returnPathname` option to specify the destination route.

```typescript
// app/routes/callback.ts
import { authLoader } from '@workos-inc/authkit-react-router';

// Redirect users to /dashboard after successful authentication
export const loader = authLoader({
  returnPathname: '/dashboard'
});
```

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

### Low-Level Access Token with `withAuth` in AuthKit React Router

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

Provides direct access to authentication data, including the access token, using the `withAuth` function. This is for advanced use cases where manual control over token refresh and session management is needed. It requires manual redirect handling for unauthenticated users.

```tsx
import { withAuth } from '@workos-inc/authkit-react-router';
import { redirect, type LoaderFunctionArgs } from 'react-router';

export const loader = async (args: LoaderFunctionArgs) => {
  const auth = await withAuth(args);
  
  if (!auth.user) {
    // Manual redirect - withAuth doesn't handle this automatically
    throw redirect('/sign-in');
  }
  
  // Access token is directly available as a property
  const { accessToken, user, sessionId } = auth;
  
  // Use the token for server-side operations
  const apiData = await fetch('https://api.example.com/data', {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  
  // Be careful what you return - accessToken will be exposed if included
  return {
    user,
    apiData: await apiData.json(),
    // accessToken, // ⚠️ Only include if client-side access is necessary
  };
};
```

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

### Configure AuthKit Programmatically in TypeScript

Source: https://context7.com/workos/authkit-react-router/llms.txt

Initialize AuthKit authentication within a React Router application using programmatic configuration in TypeScript. This allows for setting required credentials and customizing session cookie properties like name, age, and API connection details.

```typescript
import { configure } from '@workos-inc/authkit-react-router';

// Basic configuration with required values
configure({
  clientId: 'client_1234567890',
  apiKey: 'sk_test_1234567890',
  redirectUri: 'http://localhost:5173/callback',
  cookiePassword: 'your-secure-cookie-password-at-least-32-chars',
});

// Advanced configuration with optional settings
configure({
  clientId: 'client_1234567890',
  apiKey: 'sk_test_1234567890',
  redirectUri: 'http://localhost:5173/callback',
  cookiePassword: 'your-secure-cookie-password-at-least-32-chars',
  cookieName: 'my-custom-session-cookie',
  cookieMaxAge: 60 * 60 * 24 * 30, // 30 days in seconds
  apiHttps: true,
  apiHostname: 'api.workos.com',
  apiPort: 443,
});
```

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

### Default AuthKit Session Storage Configuration

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

This object shows the default configuration for cookie-based session storage used by AuthKit. It includes settings like cookie name, path, security flags, and expiration. These can be overridden by environment variables like WORKOS_COOKIE_NAME and WORKOS_COOKIE_MAX_AGE.

```typescript
{
  name: "wos-session", // Default or WORKOS_COOKIE_NAME if set
  path: "/",
  httpOnly: true,
  secure: true, // When redirect URI uses HTTPS
  sameSite: "lax",
  maxAge: 34560000, // 400 days (configurable via WORKOS_COOKIE_MAX_AGE)
  secrets: [/* your cookie password, configurable via WORKOS_COOKIE_PASSWORD */],
}
```

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

### Permission-Based Feature Access with React Router

Source: https://context7.com/workos/authkit-react-router/llms.txt

This code snippet illustrates how to control access to features based on specific user permissions. It checks if the authenticated user has the required permissions (e.g., 'documents:read', 'documents:write') before allowing them to view or interact with specific resources like documents.

```typescript
// app/routes/documents/$documentId.tsx
import { type LoaderFunctionArgs, data, redirect } from 'react-router';
import { authkitLoader } from '@workos-inc/authkit-react-router';
import { db } from '~/lib/database';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ params, auth }) => {
    if (!auth.user) {
      throw redirect('/sign-in');
    }

    const documentId = params.documentId;
    const document = await db.documents.findById(documentId);

    if (!document) {
      return data({ error: 'Document not found' }, { status: 404 });
    }

    // Check specific permissions
    const canView = auth.permissions?.includes('documents:read');
    const canEdit = auth.permissions?.includes('documents:write');
    const canDelete = auth.permissions?.includes('documents:delete');

    if (!canView) {
      return data({ error: 'No permission to view document' }, { status: 403 });
    }

    return data({
      document,
      permissions: {
        canView,
        canEdit,
        canDelete,
      },
    });
  }, { ensureSignedIn: true });

```

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

### Manual Session Refresh - TypeScript React Router API

Source: https://context7.com/workos/authkit-react-router/llms.txt

API endpoint to manually refresh user session. Calls refreshSession helper and returns updated session data including user, sessionId, organizationId, and expiration. Dependencies: @workos-inc/authkit-react-router, react-router. Inputs: Request object. Outputs: JSON response with session data or error.

```typescript
// app/routes/api/refresh-session.tsx
import { type ActionFunctionArgs, data } from 'react-router';
import { refreshSession } from '@workos-inc/authkit-react-router';

export async function action({ request }: ActionFunctionArgs) {
  try {
    const auth = await refreshSession(request);

    return data(
      {
        success: true,
        user: auth.user,
        sessionId: auth.sessionId,
        organizationId: auth.organizationId,
        expiresAt: new Date(Date.now() + 3600000).toISOString(), // 1 hour
      },
      {
        headers: auth.headers,
      }
    );
  } catch (error) {
    console.error('Session refresh failed:', error);
    return data(
      { success: false, error: 'Failed to refresh session' },
      { status: 401 }
    );
  }
}
```
Tokens:
Raw