User Management

Easy to use authentication APIs designed to provide a flexible, secure, and fast integration.

Introduction

Integrating User Management features into your app is quick and easy. 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 available to help with your integration.

Before getting started

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

A WorkOS account

Your WorkOS API Key and Client ID

1. Configure your project

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

Architecture

Server and clientClient-side only

Frontend

Next.js Remix Vanilla React

Install dependencies

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

 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. We’ll create this endpoint in the next step.

You can set a redirect URI in the Redirects section of the WorkOS Dashboard. While wildcards in your URIs can be used in the staging environment, they and query parameters cannot be used in production.

When users sign out of their application, they will be redirected to your app’s homepage which is configured in the same dashboard area.

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.

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 or the openssl library via the command line:

Generate a strong password

 openssl rand -base64 24

The code examples use your staging API keys when signed in

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 and add the following:

/routes/callback.ts

JavaScript

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

export const loader = authLoader();

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.

authkit-remix example

JavaScript

 import { json } from '@remix-run/node';
import { Form, Link, useLoaderData } from '@remix-run/react';
import {
  getSignInUrl,
  getSignUpUrl,
  authkitLoader,
} from '@workos-inc/authkit-remix';

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

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

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

Protected routes

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

/routes/protected-route.tsx

JavaScript

 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 homepage, which is configured in the WorkOS dashboard.

authkit-remix logout example

JavaScript

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

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

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

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

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

If you haven’t configured your app’s homepage in the WorkOS dashboard, users will see an error when logging out.

Validate the authentication flow

Navigate to the authentication endpoint we created 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.

Example appsView sample User Management apps

Up next