Package Exports

@workos-inc/authkit-react
@workos-inc/authkit-react/dist/index.js
@workos-inc/authkit-react/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@workos-inc/authkit-react) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

@workos-inc/authkit-react