AuthKit React Router Library

> [!IMPORTANT]
> This is an early-stage port of authkit-remix to support React Router. The features focus on framework mode (e.g. Remix), with more planned support for library mode and more features.

The AuthKit library for React Router 7+ provides convenient helpers for authentication and session management using WorkOS & AuthKit with React Router. You can find this library in action in the react-router-authkit-example repo.

Installation

Install the package with:

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

or

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

Configuration

AuthKit for React Router offers a flexible configuration system that allows you to customize various settings. You can configure the library in three ways:

$3

The simplest way is to set environment variables in your .env.local file:

`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="" # generate a secure password here
`

$3

You can also configure AuthKit programmatically by importing the configure function:

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

$3

For non-standard environments (like Deno or Edge functions), you can provide a custom environment variable source:

> [!Warning]
>
> While this library includes support for custom environment sources that could theoretically work in non-Node.js runtimes like Deno or Edge functions, this functionality has not been extensively tested (yet). If you're planning to use AuthKit in these environments, you may encounter unexpected issues. We welcome feedback and contributions from users who test in these environments.

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

$3

When retrieving configuration values, AuthKit follows this priority order:

1. Programmatically provided values via configure()
2. Environment variables (prefixed with WORKOS_)
3. Default values for optional settings

$3

> [!NOTE]
>
> To print out the entire config, a getFullConfig function is provided for debugging purposes.

| Option | Environment Variable | Default | Required | Description |
| ---------------- | ------------------------ | --------------------- | -------- | --------------------------------------------- |
| clientId | WORKOS_CLIENT_ID | - | Yes | Your WorkOS Client ID |
| apiKey | WORKOS_API_KEY | - | Yes | Your WorkOS API Key |
| redirectUri | WORKOS_REDIRECT_URI | - | Yes | The callback URL configured in WorkOS |
| cookiePassword | WORKOS_COOKIE_PASSWORD | - | Yes | Password for cookie encryption (min 32 chars) |
| cookieName | WORKOS_COOKIE_NAME | wos-session | No | Name of the session cookie |
| apiHttps | WORKOS_API_HTTPS | true | No | Whether to use HTTPS for API calls |
| cookieMaxAge | WORKOS_COOKIE_MAX_AGE | 34560000 (400 days) | No | Maximum age of cookie in seconds |
| apiHostname | WORKOS_API_HOSTNAME | api.workos.com | No | WorkOS API hostname |
| apiPort | WORKOS_API_PORT | - | No | Port to use for API calls |

> [!NOTE]
>
> The cookiePassword must be at least 32 characters long for security reasons.

Setup

$3

AuthKit requires that you have a callback URL to redirect users back to after they've authenticated. In your React Router app, create a new route and add the following:

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

export const loader = authLoader();
`

Make sure this route matches the WORKOS_REDIRECT_URI variable and the configured redirect URI in your WorkOS dashboard. For instance if your redirect URI is http://localhost:2884/callback then you'd put the above code in /app/routes/callback.ts.

You can also control the pathname the user will be sent to after signing-in by passing a returnPathname option to authLoader like so:

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

If your application needs to persist oauthTokens or other auth-related information after the callback is successful, you can pass an onSuccess option:

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

Usage

$3

Use authkitLoader to configure AuthKit for your React Router application routes.

`tsx
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() {
// Retrieves the user from the session or returns null if no user is signed in
// Other supported values include sessionId, organizationId,
// role, permissions, entitlements, featureFlags, and impersonator.
const { user, signInUrl, signUpUrl } = useLoaderData();

return (



);
}
`

For pages where you want to display a signed-in and signed-out view, use authkitLoader to retrieve the user profile from WorkOS. You can pass in additional data by providing a loader function directly to authkitLoader.

`tsx
import { type ActionFunctionArgs, type LoaderFunctionArgs, data, Form, Link, useLoaderData } 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();

if (!user) {
return (
<>
Log in


Sign Up

);
}

return (





Welcome back {user?.firstName && , ${user?.firstName}}


Sign out

);
}


`

$3

For pages where a signed-in user is mandatory, you can use the ensureSignedIn option:

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

Enabling ensureSignedIn will redirect users to AuthKit if they attempt to access the page without being authenticated.

$3

Use the signOut method to sign out the current logged in user, end the session, and redirect to your app's homepage. The homepage redirect is set in your WorkOS dashboard settings under "Redirect".

If you would like to specify where a user is redirected, an optional returnTo argument can be passed. Allowed values are configured in the WorkOS Dashboard under _Logout redirects_.

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

$3

Access tokens are available through the getAccessToken() function within your loader. This design encourages server-side token usage while making the security implications explicit.

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

#### Security Considerations

By default, access tokens are not included in the data sent to React components. This helps prevent unintentional token exposure in:

- Browser developer tools
- HTML source code
- Client-side logs or error reporting

If you need to expose the access token to client-side code, you can explicitly return it from your loader:

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

Note: Only expose access tokens to the client when necessary for your use case (e.g., making direct API calls from the browser). Consider alternatives like:

- Making API calls server-side in your loaders
- Creating proxy endpoints in your application
- Using separate client-specific tokens with limited scope

#### Using with ensureSignedIn

When using the ensureSignedIn option, you can be confident that getAccessToken() will always return a valid 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 },
);
`

$3

For advanced use cases, the withAuth function provides direct access to authentication data, including the access token. Unlike authkitLoader, this function:

- Does not handle automatic token refresh
- Does not manage cookies or session updates
- Returns the access token directly as a property
- 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
};
};
`

When to use withAuth vs authkitLoader:

- Use authkitLoader for most cases - it handles token refresh, cookies, and provides safer defaults
- Use withAuth when you need more control or are building custom authentication flows
- withAuth is useful for API routes or middleware where you don't need the full loader functionality

$3

For advanced use cases or functionality not covered by the helper methods, you can access the underlying WorkOS client directly:

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

// Get the configured WorkOS client instance
const workos = getWorkOS();

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

$3

While the standard authentication flow handles session management automatically, some use cases require manually creating and storing a session. This is useful for custom authentication flows like email verification or token exchange.

For these scenarios, you can use the saveSession function:

`ts
import { redirect } from 'react-router';
import { getWorkOS, saveSession } from '@workos-inc/authkit-react-router';

// Example: Email verification flow
async function handleEmailVerification(request: Request) {
const { code } = await request.json();

// Authenticate with the WorkOS API directly
const authResponse = await getWorkOS().userManagement.authenticateWithEmailVerification({
clientId: process.env.WORKOS_CLIENT_ID,
code,
});

// Save the session data to a cookie
await saveSession(
{
accessToken: authResponse.accessToken,
refreshToken: authResponse.refreshToken,
user: authResponse.user,
impersonator: authResponse.impersonator,
},
request,
);

return redirect('/dashboard');
}
`

$3

To enable debug logs, pass in the debug flag when using authkitLoader.

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

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

If providing a loader function, you can pass the options object as the third parameter

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

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

Customizing Session Storage

By default, AuthKit for React Router uses cookie-based session storage with these settings:

`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 /],
}
`

$3

You can provide your own session storage implementation to both authkitLoader and authLoader:

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

For code reuse and consistency, consider using a shared function:

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

> [!NOTE]
> When deploying to serverless environments like AWS Lambda, ensure you pass the same storage configuration to both your main routes and the callback route to handle cold starts properly.

AuthKit works with any session storage that implements React Router's SessionStorage` interface, including Redis-based or database-backed implementations.