AuthKit React

Add authentication to your React app with WorkOS AuthKit. Handles sign-in, sign-up, token refresh, and session management via a hosted OAuth flow.

Installation

npm install @workos-inc/authkit-react

Quick Start

1. Configure the WorkOS Dashboard

• Add a Redirect URI (e.g. http://localhost:5173) on the Redirects page. This is where WorkOS sends users after they authenticate.
• Add your app's origin (e.g. http://localhost:5173) to the allowed origins list on the Authentication page of the WorkOS Dashboard.

2. Wrap your app in AuthKitProvider

import { AuthKitProvider } from "@workos-inc/authkit-react";
import { createRoot } from "react-dom/client";

createRoot(document.getElementById("root")).render(
  <AuthKitProvider clientId="client_01ABC123DEF456">
    <App />
  </AuthKitProvider>,
);

3. Add a /login route

Some authentication flows are initiated outside your app — for example, when an admin impersonates a user from the WorkOS Dashboard, or when a third-party triggers login via your app's sign-in endpoint. These flows redirect the user to a well-known login path in your app, which must then start the OAuth flow.

Register a /login URL (e.g. http://localhost:5173/login) as the sign-in endpoint on the same Redirects page, then handle it in your app:

import { useAuth } from "@workos-inc/authkit-react";
import { useEffect } from "react";

function LoginRoute() {
  const { signIn } = useAuth();

  useEffect(() => {
    signIn();
  }, [signIn]);

  return <div>Redirecting...</div>;
}

In a router-based app this would be a dedicated route component. In a simple app you can handle it inline:

function App() {
  const { isLoading, user, signIn } = useAuth();

  useEffect(() => {
    if (window.location.pathname === "/login") {
      signIn();
    }
  }, [signIn]);

  // ... rest of your app
}

4. Use the useAuth hook

import { useAuth } from "@workos-inc/authkit-react";

function App() {
  const { isLoading, user, signIn, signUp, signOut, getAccessToken } =
    useAuth();

  if (isLoading) return <div>Loading...</div>;

  if (!user) {
    return (
      <div>
        <button onClick={() => signIn()}>Sign In</button>
        <button onClick={() => signUp()}>Sign Up</button>
      </div>
    );
  }

  return (
    <div>
      <p>Hello, {user.firstName ?? user.email}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

That's it — you have a fully authenticated React app.

API Reference

<AuthKitProvider />

Wrap your app in this component to provide authentication context.

| Prop | Type | Required | Description | | ----------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | clientId | string | Yes | Your WorkOS Client ID (starts with client_) | | apiHostname | string | No | Your custom Authentication API domain. Defaults to api.workos.com. In production, this should be set to a domain you own (e.g. auth.example.com) | | devMode | boolean | No | Stores tokens in localStorage. Auto-enabled on localhost and 127.0.0.1. | | onRedirectCallback | (params) => void | No | Called after a successful authentication. Use to restore app state or navigate. | | onRefresh | (response) => void | No | Called when the access token is refreshed. | | onRefreshFailure | ({ signIn }) => void | No | Called when token refresh fails. Receives signIn to trigger re-authentication. | | onBeforeAutoRefresh | () => boolean | No | Called before automatic refresh. Return false to skip. | | refreshBufferInterval | number | No | Seconds before token expiration to trigger refresh. |

useAuth()

Returns the current auth state and helper methods. Must be called inside <AuthKitProvider>.

State

| Property | Type | Description | | ---------------------- | ------------------------------ | ---------------------------------------------------------- | | isLoading | boolean | true during initial authentication check | | user | User \| null | The authenticated user, or null | | organizationId | string \| null | The user's current organization | | role | string \| null | The user's role in the current organization | | roles | string[] \| null | All roles for the user in the current organization | | permissions | string[] | Permissions for the user's role | | featureFlags | string[] | Feature flags enabled for the organization | | impersonator | Impersonator \| null | Set when an admin is impersonating this user | | authenticationMethod | AuthenticationMethod \| null | How the user authenticated (e.g. "GoogleOAuth", "SSO") |

Methods

| Method | Signature | Description | | ---------------------- | ---------------------------------------------------- | ---------------------------------------------- | | signIn | (opts?) => Promise<void> | Redirect to the AuthKit sign-in page | | signUp | (opts?) => Promise<void> | Redirect to the AuthKit sign-up page | | signOut | (opts?) => void | End the session and sign the user out | | getAccessToken | (opts?) => Promise<string> | Get a valid access token, refreshing if needed | | getUser | () => User \| null | Synchronously get the current user | | switchToOrganization | ({ organizationId, signInOpts? }) => Promise<void> | Switch to a different organization | | getSignInUrl | (opts?) => Promise<string> | Get the sign-in URL without redirecting | | getSignUpUrl | (opts?) => Promise<string> | Get the sign-up URL without redirecting |

signIn / signUp Options

{
  state?: any;                // Data to persist through the auth flow
  organizationId?: string;    // Pre-select an organization
  loginHint?: string;         // Pre-fill the email field
  invitationToken?: string;   // Accept an invitation during sign-up
  screenHint?: "sign-in" | "sign-up"; // Which screen to show
}

signOut Options

{
  returnTo?: string;   // URL to navigate to after sign-out
}

User

interface User {
  id: string;
  email: string;
  emailVerified: boolean;
  profilePictureUrl: string | null;
  firstName: string | null;
  lastName: string | null;
  createdAt: string;
  updatedAt: string;
  lastSignInAt: string | null;
  externalId: string | undefined;
}

getClaims(accessToken)

Decodes a JWT access token and returns its claims.

import { getClaims } from "@workos-inc/authkit-react";

const token = await getAccessToken();
const claims = getClaims(token);
// claims.sub, claims.org_id, claims.role, claims.permissions, etc.

Error Classes

• AuthKitError — Base error class for AuthKit errors.
• LoginRequiredError — Thrown by getAccessToken() when no user is authenticated.

Recipes

Making Authenticated API Calls

function Dashboard() {
  const { getAccessToken } = useAuth();

  async function fetchData() {
    const token = await getAccessToken();
    const res = await fetch("/api/data", {
      headers: { Authorization: `Bearer ${token}` },
    });
    return res.json();
  }

  // ...
}

Passing Data Through Auth Flows

Use state to preserve data across the authentication redirect:

// Pass state when starting sign-in
<button onClick={() => signIn({ state: { returnTo: "/dashboard" } })}>
  Sign In
</button>

// Retrieve it in onRedirectCallback
<AuthKitProvider
  clientId="client_01ABC123DEF456"
  onRedirectCallback={({ state }) => {
    if (state?.returnTo) {
      window.location.href = state.returnTo;
    }
  }}
>
  <App />
</AuthKitProvider>

Handling Token Refresh Failures

<AuthKitProvider
  clientId="client_01ABC123DEF456"
  onRefreshFailure={({ signIn }) => {
    // Session expired — prompt re-authentication
    signIn();
  }}
>
  <App />
</AuthKitProvider>

Multi-Organization Switching

function OrgSwitcher({ organizations }) {
  const { switchToOrganization, organizationId } = useAuth();

  return (
    <select
      value={organizationId ?? ""}
      onChange={(e) => switchToOrganization({ organizationId: e.target.value })}
    >
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name}
        </option>
      ))}
    </select>
  );
}

Role-Based UI

function AdminPanel() {
  const { role, permissions } = useAuth();

  if (role !== "admin") return null;

  return (
    <div>
      <h2>Admin Panel</h2>
      {permissions.includes("users:manage") && <UserManagement />}
    </div>
  );
}