<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# AuthKit

## Introduction

Integrating AuthKit into your app can be done in less than ten minutes. In this guide, we'll walk you through adding a hosted authentication flow to your application using AuthKit.

In addition to this guide, there are a variety of [example apps](https://workos.com/docs/authkit/example-apps) available to help with your integration.

## Before getting started

To get the most out of this guide, you'll need:

- A [WorkOS account](https://dashboard.workos.com/)
- Your WorkOS [API Key](https://workos.com/docs/glossary/api-key) and [Client ID](https://workos.com/docs/glossary/client-id)

***

## (1) Configure your project

Let's add the necessary dependencies and configuration in your WorkOS Dashboard.

### Install dependencies

To use AuthKit with a Remix application, use the `authkit-remix` library. Start by installing it in your Remix project via `npm`.

```bash title="Install Remix SDK"
npm install @workos-inc/authkit-remix
```

### Configure a redirect URI

A redirect URI is a callback endpoint that WorkOS will redirect to after a user has authenticated. This endpoint will exchange the authorization code returned by WorkOS for an authenticated [User object](https://workos.com/docs/reference/authkit/user). We'll create this endpoint in the next step.

You can set a redirect URI in the [Applications](https://dashboard.workos.com/environment/applications) section of the WorkOS Dashboard. Open your application and go to the **Redirects** tab to add a redirect URI. We recommend using `http://localhost:3000/callback` as the default here.

WorkOS supports using wildcard characters in Redirect URIs, but not for the default Redirect URI. More information about wildcard characters support can be found in the [Redirect URIs](https://workos.com/docs/sso/redirect-uris/wildcard-characters) guide.

![Dashboard redirect URI](https://images.workoscdn.com/images/a9671531-b377-4fb1-b056-4181ae92c25f.png?auto=format\&fit=clip\&q=80)

When users sign out of their application, they will be redirected to your app's [Sign-out URI](https://workos.com/docs/authkit/sessions#sign-out-uris) which is configured in the same dashboard area.

### Configure Initiate login URI

Sign-in requests should originate from your application. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted sign-in page or they might be led directly to the hosted sign-in page when clicking on a password reset or invitation link in an email.

In these cases, AuthKit will detect when a sign-in request did not originate at your application and redirect to your application's Initiate login URI. This is an endpoint that you define at your application that redirects users to sign in using AuthKit. We'll create this endpoint in the next step. Password reset and invitation details are preserved through this redirect, so users continue on to the correct page as long as your Initiate login URI starts an AuthKit sign-in rather than rendering your own sign-in page.

You can configure the Initiate login URI from your application's **Redirects** tab in the [Applications](https://dashboard.workos.com/environment/applications) section of the WorkOS Dashboard.

![Initiate login URI](https://images.workoscdn.com/images/25b53ea7-95ba-48cc-b6e7-ccd1b1bc35eb.png?auto=format\&fit=clip\&q=80)

### Set secrets

To make calls to WorkOS, provide the API key and the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app's configuration depending on your preferences.

```plain title="Environment variables"
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

WORKOS_REDIRECT_URI="http://localhost:3000/callback" # configured in the WorkOS dashboard
WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
```

The SDK requires you to set a strong password to encrypt cookies. This password must be at least 32 characters long. You can generate a secure password by using the [1Password generator](https://1password.com/password-generator/) or the `openssl` library via the command line:

```bash title="Generate a strong password"
openssl rand -base64 32
```

> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)

***

## (2) Add AuthKit to your app

Let's integrate the hosted authentication flow into your app.

### Callback route

When a user has authenticated via AuthKit, they will be redirected to your app's callback route. In your Remix app, [create a new route](https://remix.run/docs/en/main/discussion/routes) and add the following:

:::code-group{title="/routes/callback.ts"}

```js language="js"
import { authLoader } from '@workos-inc/authkit-remix';

export const loader = authLoader();
```

:::

### Initiate login URI

We'll need an Initiate login URI to direct users to sign in using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.

:::code-group{title="/routes/login.ts"}

```js language="js"
import { redirect } from '@remix-run/node';
import { getSignInUrl } from '@workos-inc/authkit-remix';

export const loader = async () => {
  const signInUrl = await getSignInUrl();

  return redirect(signInUrl);
};
```

:::

### Access authentication data in your Remix application

We'll need to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.

Use `authkitLoader` to configure AuthKit for your Remix application routes. You can choose to return custom data from your loader, like for instance the sign in and sign out URLs.

:::code-group{title="/app/routes/_index.jsx"}

```jsx language="jsx"
import { json } from '@remix-run/node';
import { Form, Link, useLoaderData } from '@remix-run/react';
import { getSignUpUrl, authkitLoader } from '@workos-inc/authkit-remix';

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

export default function Index() {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user, signUpUrl } = useLoaderData();

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

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

:::

### Protected routes

For routes where a signed in user is mandatory, you can use the `ensureSignedIn` option in your loader.

:::code-group{title="/app/protected/route.tsx"}

```jsx language="jsx"
import { Form, useLoaderData } from '@remix-run/react';
import { authkitLoader } from '@workos-inc/authkit-remix';

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

export default function ProtectedPage() {
  // If the user isn't signed in, they will be automatically redirected to AuthKit
  const { user } = useLoaderData();

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

:::

### Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Sign-out URI](https://workos.com/docs/authkit/sessions#sign-out-uris), which is configured in the WorkOS dashboard.

:::code-group{title="/app/routes/_index.jsx"}

```jsx language="jsx"
import { json } from '@remix-run/node';
import { Form, Link, useLoaderData } from '@remix-run/react';
import {
  getSignUpUrl,
  authkitLoader,
  // +diff-start
  signOut,
  // +diff-end
} from '@workos-inc/authkit-remix';

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

// +diff-start
export async function action({ request }) {
  return await signOut(request);
}
// +diff-end

export default function Index() {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user, signUpUrl } = useLoaderData();

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

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

:::

> If you haven't configured a [Sign-out URI](https://workos.com/docs/authkit/sessions#sign-out-uris) in the WorkOS dashboard, users will see an error when logging out.

## Validate the authentication flow

To test all of this out, call `npm run dev`, navigate to `localhost:3000`, and sign up for an account.

You can then sign in with the newly created credentials and see the user listed in the **Users** section of the [WorkOS Dashboard](https://dashboard.workos.com).

![Dashboard showing newly created user](https://images.workoscdn.com/images/54fa6e6c-4c6f-4959-9301-344aeb4eeac8.png?auto=format\&fit=clip\&q=80)
