AuthKit Remix

https://github.com/workos/authkit-remix
Admin
The AuthKit library for Remix provides convenient helpers for authentication and session management...
Tokens:9,557
Snippets:49
Trust Score:10
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install AuthKit Remix Package

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

Instructions for installing the AuthKit Remix library using npm or yarn.

```bash
npm i @workos-inc/authkit-remix
```

```bash
yarn add @workos-inc/authkit-remix
```

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

### Configuration Setup

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

Configure AuthKit using environment variables or programmatically for flexible deployment. This includes setting up client ID, API key, redirect URI, and cookie-related options.

```APIDOC
## Configuration Setup

### Description
Configure AuthKit with environment variables or programmatically for flexible deployment.

### Method
`configure` function

### Endpoint
N/A (Programmatic configuration)

### Parameters
#### Request Body
- **clientId** (string) - Required - Your WorkOS client ID.
- **apiKey** (string) - Required - Your WorkOS API key.
- **redirectUri** (string) - Required - The URI to redirect to after authentication.
- **cookiePassword** (string) - Required - A secure password for cookie encryption (at least 32 characters).
- **cookieName** (string) - Optional - The name of the session cookie (defaults to 'wos-session').
- **apiHttps** (boolean) - Optional - Whether to use HTTPS for API calls (defaults to true).
- **cookieMaxAge** (number) - Optional - The maximum age of the session cookie in seconds (defaults to 400 days).

### Request Example
```typescript
import { configure } from '@workos-inc/authkit-remix';

configure({
  clientId: 'client_1234567890',
  apiKey: 'sk_test_1234567890',
  redirectUri: 'http://localhost:5173/callback',
  cookiePassword: 'your-secure-cookie-password-at-least-32-characters-long'
});
```

### Response
No direct response, configuration is applied internally.
```

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

### Configure AuthKit with Environment Variables

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

Example of configuring AuthKit using environment variables in a .env.local file. Requires client ID, API key, redirect URI, and a cookie password.

```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 Custom Session Storage for AuthKit in Remix

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

Set up custom session storage backends for WorkOS AuthKit in Remix applications. This example demonstrates creating both cookie-based storage (default) and memory-based storage for testing purposes. It shows how to integrate these storage configurations with `authkitLoader` and `authLoader`.

```typescript
// app/lib/session.ts
import { createCookieSessionStorage, createMemorySessionStorage } from "@remix-run/node";
import { authkitLoader, authLoader } from "@workos-inc/authkit-remix";

// Cookie-based storage (default)
export function getCookieStorage() {
  const storage = createCookieSessionStorage({
    cookie: {
      name: "auth-session",
      secrets: ["your-secret-key-at-least-32-characters"],
      sameSite: "lax",
      path: "/",
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      maxAge: 60 * 60 * 24 * 30 // 30 days
    }
  });
  return { storage, cookie: { name: "auth-session" } };
}

// Memory-based storage (for testing)
export function getMemoryStorage() {
  const storage = createMemorySessionStorage({
    cookie: {
      name: "auth-session-memory",
      secrets: ["test-secret"],
      sameSite: "lax",
      path: "/",
      httpOnly: true,
      secure: false,
      maxAge: 60 * 60 * 24
    }
  });
  return { storage, cookie: { name: "auth-session-memory" } };
}

// app/routes/dashboard.tsx
import { getCookieStorage } from "~/lib/session";

export const loader = (args) => authkitLoader(args, {
  ...getCookieStorage(),
  ensureSignedIn: true,
  debug: true, // Enable debug logging
  onSessionRefreshSuccess: async ({ accessToken, user, organizationId }) => {
    console.log(`Session refreshed for user ${user.email}`);
  },
  onSessionRefreshError: async ({ error, request, sessionData }) => {
    console.error('Session refresh failed:', error);
    // Optionally return custom error response
    // return new Response('Session expired', { status: 401 });
  }
});

// app/routes/callback.ts
import { getCookieStorage } from "~/lib/session";

export const loader = authLoader({
  ...getCookieStorage(),
  returnPathname: '/dashboard'
});

```

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

### Conditional UI with AuthKit Loader in Remix

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

Enables displaying different views for signed-in and signed-out users by leveraging `authkitLoader`. This example customizes the loader to fetch sign-in and sign-up URLs, and provides an action to handle user sign-out. It allows conditional rendering of login/signup links or a welcome message with a sign-out button.

```tsx
import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';
import { Form, Link, useLoaderData } from '@remix-run/react';
import { getSignInUrl, getSignUpUrl, signOut, authkitLoader } from '@workos-inc/authkit-remix';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ request, auth }) => {
    return {
      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 Source

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

Configuring AuthKit for non-Node.js environments like Deno or Edge functions by providing a custom environment variable source function. This example uses Deno's `Deno.env.get`.

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

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

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

### Get Access Token in Remix Loader with AuthKit

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

Demonstrates how to retrieve an access token within a Remix loader function using AuthKit's `getAccessToken()` function. This approach promotes server-side token usage for enhanced security. The example shows how to use the token to authorize requests to an external API. Access tokens are not exposed to client-side code by default.

```tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { authkitLoader } from '@workos-inc/authkit-remix';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ auth, getAccessToken }) => {
    if (!auth.user) {
      // Not signed in - getAccessToken() would return null
      return { 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: await serviceData.json(),
    };
  });
```

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

### Custom Session Storage Implementation

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

Allows customization of session storage by providing a custom `SessionStorage` implementation to `authkitLoader` and `authLoader`. This example uses `createMemorySessionStorage` for demonstration, but any Remix-compatible storage (e.g., Redis, database) can be used.

```ts
import { createMemorySessionStorage } from "@remix-run/node";
import { authkitLoader, authLoader } from "@workos-inc/authkit-remix";

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

```ts
// 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...
});
```

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

### Remix: Handle Public/Protected Views with Custom Loader

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

This example shows how to create a Remix route that serves different content based on user authentication status. It uses `authkitLoader` to manage authentication state and allows for custom data fetching for both authenticated and unauthenticated users. Sign-in and sign-up URLs are generated for unauthenticated users, while authenticated users can fetch custom data using their access token.

```tsx
// app/routes/_index.tsx
import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';
import { Form, Link, useLoaderData } from '@remix-run/react';
import { getSignInUrl, getSignUpUrl, signOut, authkitLoader } from '@workos-inc/authkit-remix';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, async ({ request, auth, getAccessToken }) => {
    // Custom loader logic that runs for both authenticated and unauthenticated users
    if (auth.user) {
      // Fetch user-specific data
      const accessToken = getAccessToken();
      const userData = await fetch('https://api.example.com/user/data', {
        headers: { Authorization: `Bearer ${accessToken}` }
      }).then(res => res.json());

      return {
        userData,
        signInUrl: null,
        signUpUrl: null,
      };
    } else {
      // Generate auth URLs for unauthenticated users
      return {
        userData: null,
        signInUrl: await getSignInUrl(),
        signUpUrl: await getSignUpUrl(),
      };
    }
  });

export async function action({ request }: ActionFunctionArgs) {
  // Handle sign out with custom redirect
  return await signOut(request, { returnTo: 'https://example.com' });
}

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

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

  return (
    <Form method="post">
      <h1>Welcome back, {user.firstName}!</h1>
      {userData && (
        <div>
          <h2>Your Data:</h2>
          <pre>{JSON.stringify(userData, null, 2)}</pre>
        </div>
      )}
      <button type="submit">Sign out</button>
    </Form>
  );
}

```

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

### Remix: Low-Level Auth with `withAuth`

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

This example demonstrates using `withAuth` for advanced scenarios where direct access to authentication data is needed without automatic session management. It allows manual handling of redirects and provides direct access to the access token, user details, session ID, organization ID, and permissions for server-side operations. The access token is not returned to the client.

```ts
// app/routes/api.user-status.ts
import { withAuth } from '@workos-inc/authkit-remix';
import { redirect, json } from '@remix-run/node';
import type { LoaderFunctionArgs } from '@remix-run/node';

export const loader = async (args: LoaderFunctionArgs) => {
  // withAuth provides direct access to auth data without automatic refresh
  const auth = await withAuth(args);

  if (!auth.user) {
    // Manual redirect handling - withAuth doesn't do this automatically
    throw redirect('/sign-in');
  }

  // Access token is directly available as a property
  const { accessToken, user, sessionId, organizationId, permissions } = auth;

  // Perform server-side operations with the access token
  const userStatus = await fetch('https://api.example.com/status', {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'X-Organization-ID': organizationId || '',
    }
  }).then(res => res.json());

  // Return only necessary data (NOT the access token)
  return json({
    status: userStatus,
    user: {
      id: user.id,
      email: user.email,
      firstName: user.firstName,
    },
    sessionId,
    organizationId,
    hasAdminPermission: permissions?.includes('admin') || false,
  });
};

```

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

### Configure AuthKit Authentication

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

Sets up the AuthKit library for Remix applications. It can be configured programmatically using an options object or by referencing environment variables. This setup handles essential authentication parameters such as client ID, API key, redirect URI, and cookie settings. It also supports custom environment variable sources for non-standard deployment environments.

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

// Programmatic configuration
configure({
  clientId: 'client_1234567890',
  apiKey: 'sk_test_1234567890',
  redirectUri: 'http://localhost:5173/callback',
  cookiePassword: 'your-secure-cookie-password-at-least-32-characters-long',
  cookieName: 'my-custom-cookie-name', // Optional, defaults to 'wos-session'
  apiHttps: true, // Optional, defaults to true
  cookieMaxAge: 60 * 60 * 24 * 30, // Optional, defaults to 400 days
});

// Or use environment variables in .env.local:
// WORKOS_CLIENT_ID="client_..."
// WORKOS_API_KEY="sk_test_..."
// WORKOS_REDIRECT_URI="http://localhost:5173/callback"
// WORKOS_COOKIE_PASSWORD="<your password>"

// For non-standard environments (Deno, Edge functions)
configure(key => Deno.env.get(key));

// Combine explicit values with custom environment source
configure(
  { clientId: 'client_1234567890' },
  key => Deno.env.get(key)
);
```

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

### Expose Access Token to Client in Remix Loader

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

Illustrates how to explicitly expose an access token to client-side code from a Remix loader function using AuthKit. This should be done cautiously and only when necessary, such as for direct API calls from the browser. The example shows returning the `accessToken` alongside other data, with `ensureSignedIn` enabled.

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

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

### Remix: Use Access Token for Server-Side API Calls

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

This example demonstrates how to securely retrieve and use an access token within Remix server-side operations. The `authkitLoader` is configured with `ensureSignedIn: true` to guarantee an authenticated user, and `getAccessToken()` is used to obtain the token for making authorized API requests. The access token is never exposed to the client.

```tsx
// app/routes/api-data.tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { authkitLoader } from '@workos-inc/authkit-remix';

export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(
    args,
    async ({ auth, getAccessToken }) => {
      // getAccessToken() returns the token, guaranteed to exist with ensureSignedIn: true
      const accessToken = getAccessToken();

      // Use token for authenticated API calls
      const [profileData, settingsData] = await Promise.all([
        fetch('https://api.example.com/profile', {
          headers: { Authorization: `Bearer ${accessToken}` }
        }).then(res => res.json()),
        fetch('https://api.example.com/settings', {
          headers: { Authorization: `Bearer ${accessToken}` }
        }).then(res => res.json())
      ]);

      return {
        profileData,
        settingsData,
        // Note: accessToken is NOT returned to client for security
      };
    },
    { ensureSignedIn: true }
  );

export default function ApiDataPage() {
  const { user, profileData, settingsData } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{user.firstName}'s Data</h1>
      <section>
        <h2>Profile</h2>
        <pre>{JSON.stringify(profileData, null, 2)}</pre>
      </section>
      <section>
        <h2>Settings</h2>
        <pre>{JSON.stringify(settingsData, null, 2)}</pre>
      </section>
    </div>
  );
}

```

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

### Generate Sign In/Up URLs with Return Paths (Remix)

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

Generates different sign-in and sign-up URLs with specified return paths for custom authentication flows in a Remix application. It uses `getSignInUrl` and `getSignUpUrl` from AuthKit Remix to create these URLs. The function handles both default returns to the homepage and specific returns to paths like '/checkout' or '/dashboard'.

```tsx
// app/routes/custom-auth.tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData, Link } from '@remix-run/react';
import { getSignInUrl, getSignUpUrl, authkitLoader } from '@workos-inc/authkit-remix';

export const loader = async (args: LoaderFunctionArgs) => {
  return authkitLoader(args, async ({ auth }) => {
    if (auth.user) {
      return {
        signInUrl: null,
        signUpUrl: null,
        checkoutSignInUrl: null,
      };
    }

    // Generate different auth URLs for different flows
    const [
      defaultSignInUrl,
      defaultSignUpUrl,
      checkoutSignInUrl,
      dashboardSignUpUrl,
    ] = await Promise.all([
      getSignInUrl(), // Returns to homepage
      getSignUpUrl(), // Returns to homepage
      getSignInUrl('/checkout'), // Returns to checkout after auth
      getSignUpUrl('/dashboard'), // Returns to dashboard after auth
    ]);

    return {
      signInUrl: defaultSignInUrl,
      signUpUrl: defaultSignUpUrl,
      checkoutSignInUrl,
      dashboardSignUpUrl,
    };
  });
};

export default function CustomAuthPage() {
  const data = useLoaderData<typeof loader>();

  if (data.user) {
    return (
      <div>
        <h1>You're already signed in as {data.user.email}</h1>
        <Link to="/dashboard">Go to Dashboard</Link>
      </div>
    );
  }

  return (
    <div>
      <h1>Choose Your Path</h1>

      <section>
        <h2>New User</h2>
        <Link to={data.signUpUrl!}>Sign Up</Link>
        <br />
        <Link to={data.dashboardSignUpUrl!}>Sign Up & Go to Dashboard</Link>
      </section>

      <section>
        <h2>Existing User</h2>
        <Link to={data.signInUrl!}>Sign In</Link>
        <br />
        <Link to={data.checkoutSignInUrl!}>Sign In & Continue to Checkout</Link>
      </section>
    </div>
  );
}

```

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

### Configure AuthKit Loader in Remix

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

Sets up the `authkitLoader` for Remix application routes to access authentication data. It retrieves user information and relevant URLs from the session, returning null if no user is signed in. Supported data includes user details, session, organization, role, permissions, entitlements, and impersonator information.

```tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { authkitLoader } from '@workos-inc/authkit-remix';

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

export function App() {
  // Retrieves the user from the session or returns `null` if no user is signed in
  // Other supported values include `sessionId`, `organizationId`,
  // `role`, `permissions`, `entitlements`, and `impersonator`.
  const { user, signInUrl, signUpUrl } = useLoaderData<typeof loader>();

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

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

### AuthKit Remix Callback Route Loader

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

Setting up the callback route in a Remix application using the `authLoader` function. This route handles the redirection after user authentication. It can optionally specify a `returnPathname` and an `onSuccess` callback for persisting tokens.

```typescript
import { authLoader } from '@workos-inc/authkit-remix';

export const loader = authLoader();
```

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

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

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

### Authentication Callback Route

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

Set up the OAuth callback route to handle user authentication redirects. This route is responsible for processing the callback from WorkOS after a user signs in.

```APIDOC
## Authentication Callback Route

### Description
Set up the OAuth callback route to handle user authentication redirects.

### Method
`authLoader` function from `@workos-inc/authkit-remix`

### Endpoint
`/callback` (or your configured redirect URI)

### Parameters
#### Request Body
- **returnPathname** (string) - Optional - The pathname to redirect to after successful authentication (defaults to '/').
- **onSuccess** (function) - Optional - A callback function executed after successful authentication. It receives authentication tokens, user information, and other details. Use this to persist tokens or perform post-authentication logic.

### Request Example
```typescript
// app/routes/callback.ts
import { authLoader } from '@workos-inc/authkit-remix';

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

// With custom return pathname
export const loader = authLoader({
  returnPathname: '/dashboard'
});

// With success callback
export const loader = authLoader({
  returnPathname: '/dashboard',
  onSuccess: async ({ oauthTokens, user, accessToken, refreshToken, organizationId, impersonator }) => {
    // Save tokens to database or perform other actions
    await saveToDatabase({
      userId: user.id,
      accessToken,
      refreshToken,
      oauthTokens,
      organizationId,
    });
    console.log(`User ${user.email} authenticated`);
  }
});
```

### Response
Redirects the user to the specified `returnPathname` after successful authentication.
```

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

### Programmatic AuthKit Configuration

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

Configuring AuthKit programmatically by importing and calling the `configure` function with an options object. Supports client ID, API key, redirect URI, cookie password, and optional settings like cookie name, HTTPS, and max age.

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

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

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

### Switch Organization using AuthKit in Remix

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

Implement organization switching functionality in a Remix application using WorkOS AuthKit. This snippet shows how to handle the organization switch request, validate the organization ID, and either redirect the user to a specified return page or return updated authentication data. It includes error handling for failed switches.

```tsx
// app/routes/switch-org.tsx
import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';
import { Form, useLoaderData, useActionData } from '@remix-run/react';
import { switchToOrganization, authkitLoader } from '@workos-inc/authkit-remix';

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

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

  if (!organizationId) {
    return { error: 'Organization ID is required' };
  }

  try {
    // Switch organization and redirect to dashboard
    return await switchToOrganization(request, organizationId, {
      returnTo: '/dashboard'
    });

    // Or return updated auth data without redirect
    // const result = await switchToOrganization(request, organizationId);
    // return result; // Contains { success: true, auth: {...} }
  } catch (error) {
    return {
      error: 'Failed to switch organization',
      details: error instanceof Error ? error.message : String(error)
    };
  }
}

export default function SwitchOrgPage() {
  const { user, organizationId } = useLoaderData<typeof loader>();
  const actionData = useActionData<typeof action>();

  return (
    <div>
      <h1>Switch Organization</h1>
      <p>Current: {organizationId || 'No organization'}</p>
      <p>User: {user.email}</p>

      <Form method="post">
        <label>
          Organization ID:
          <input type="text" name="organizationId" required />
        </label>
        <button type="submit">Switch Organization</button>
      </Form>

      {actionData?.error && (
        <div style={{ color: 'red' }}>
          <p>Error: {actionData.error}</p>
          {actionData.details && <p>Details: {actionData.details}</p>}
        </div>
      )}

      {actionData?.success && (
        <div style={{ color: 'green' }}>
          <p>Successfully switched to {actionData.auth.organizationId}</p>
        </div>
      )}
    </div>
  );
}

```

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

### Require Sign-In for Remix Routes with AuthKit

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

Configures the `authkitLoader` to ensure users are signed in before accessing a specific Remix route. If a user is not authenticated, they will be automatically redirected to AuthKit for login. This is achieved by setting the `ensureSignedIn` option to `true`.

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

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

### Protected Route with Authentication

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

Use `authkitLoader` to protect routes and access authentication data. This function enforces authentication and provides user details to the component.

```APIDOC
## Protected Route with Authentication

### Description
Use `authkitLoader` to access authentication data and protect routes. Ensures users are signed in before accessing the route.

### Method
`authkitLoader` function from `@workos-inc/authkit-remix`

### Endpoint
Any route you want to protect.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **args** (LoaderFunctionArgs) - Required - Arguments passed to the Remix loader function.
- **options** (object) - Optional - Configuration options for the loader.
  - **ensureSignedIn** (boolean) - Required - If true, redirects to the sign-in page if the user is not authenticated.

### Request Example
```typescript
// app/routes/dashboard.tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { authkitLoader } from '@workos-inc/authkit-remix';

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

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

  // ... component logic to display user data
}
```

### Response
#### Success Response (200)
- **user** (object) - User information object.
  - **id** (string) - User ID.
  - **email** (string) - User email.
  - **firstName** (string) - User first name.
  - **lastName** (string) - User last name.
  - ... other user properties.
- **sessionId** (string) - The ID of the current user session.
- **organizationId** (string | null) - The ID of the current organization, if applicable.
- **role** (string | null) - The role of the user within the organization, if applicable.
- **permissions** (array of strings | null) - List of permissions granted to the user, if applicable.
- **entitlements** (object | null) - Entitlements associated with the user, if applicable.

#### Response Example
```json
{
  "user": {
    "id": "user_1234567890",
    "email": "test@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "sessionId": "sess_abcdef123456",
  "organizationId": "org_zyxw987654",
  "role": "admin",
  "permissions": ["read", "write"],
  "entitlements": {"feature_x": true}
}
```
```

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

### Enabling Debug Logs in authkitLoader

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

Activates debug logging for `authkitLoader` by passing the `debug: true` option. This is useful for troubleshooting authentication flows. The debug flag can be passed directly or as part of the options object when a loader function is provided.

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

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

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

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

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

### Low-Level Access with withAuth

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

Provides direct access to authentication data like the access token for advanced use cases. It does not handle automatic token refresh or session management, requiring manual redirect handling for unauthenticated users. The access token is returned directly as a property.

```tsx
import { withAuth } from '@workos-inc/authkit-remix';
import { redirect } from '@remix-run/node';
import type { LoaderFunctionArgs } from '@remix-run/node';

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

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

### Protect Routes with AuthKit

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

Secures Remix application routes using `authkitLoader`, which ensures user authentication and provides access to user data. Routes can enforce sign-in using `ensureSignedIn: true`. The loader returns user details, session information, organization details, roles, and permissions, which can then be accessed in the component using `useLoaderData`.

```typescript
// app/routes/dashboard.tsx
import type { LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { authkitLoader } from '@workos-inc/authkit-remix';

// Simple protected route - enforces authentication
export const loader = (args: LoaderFunctionArgs) =>
  authkitLoader(args, { ensureSignedIn: true });

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

  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(perm => <li key={perm}>{perm}</li>)}
          </ul>
        </div>
      )}
    </div>
  );
}
```

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

### Sign Out User in Remix with AuthKit

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

Implements user sign-out functionality in a Remix application using AuthKit's `signOut` method. This action clears the user's session and redirects them to the application's homepage by default. An optional `returnTo` argument can be provided to specify a custom redirect URL, which must be pre-configured in WorkOS dashboard settings.

```ts
export async function action({ request }: ActionFunctionArgs) {
  // Called when the form in SignInButton is submitted
  return await signOut(request, { returnTo: 'https://example.com' });
}
```

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

### Secure Token Retrieval with ensureSignedIn

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

Ensures a valid access token is always available when using `ensureSignedIn: true`. This is ideal for loader functions where authentication is mandatory. The `getAccessToken()` function is guaranteed to return a token, simplifying API calls.

```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 });
```
Tokens:
Raw