WorkOS AuthKit: a Next.js example repo for hosted and headless login

What the AuthKit repository actually contains

AuthKit is WorkOS's login box, and this repository is the example application that ships with it. The README frames the repo as covering two integration styles: the hosted UI, described as "the fastest way to add authentication to your app with AuthKit and WorkOS User Management," and a custom UI where you build the frontend yourself against the headless WorkOS User Management APIs. Both live under src/app, in directories named using-hosted-authkit and using-your-own-ui.

The audience is narrow and specific: a developer who already has or is willing to create a WorkOS account and wants to see the flows running before committing to one of the two paths. The README's prerequisites section lists exactly one requirement, a WorkOS account, with a signup link to the dashboard. There is no self-hosted server component here, no database to provision, and no auth backend you run yourself. Everything that decides whether a login succeeds lives on WorkOS's side.

That framing matters when you read the package manifest. The name is authkit, the version is 0.1.0, and "private" is set to true. This is not a package you install from a registry. It is a runnable demo you clone, and the actual integration code you would copy into a product lives in the two published dependencies it pulls in.

Hosted UI versus headless APIs: the two paths in src/app

The split under src/app is the core design decision of the repo, and the two directories represent genuinely different trade-offs rather than two skins on the same flow.

using-hosted-authkit points at WorkOS's own pages. The README says the hosted UI "includes a fully themeable hosted UI that handles all of your authentication flows," and that when you go to production you can point it at a custom domain such as auth.yourapp.com. The consequence is that the sign-in surface is not in your codebase. You get the flows without writing them, and you accept that the pages are served by WorkOS until you configure that custom domain.

using-your-own-ui goes the other way. The README describes it as using "all of the features of AuthKit, but build out the UI yourself in your own codebase by integrating directly with the headless WorkOS User Management APIs." Here the authentication UI is self-hosted inside your application. You own the markup, the error states and the accessibility work, and in exchange the user never leaves your domain.

The repository layout supports this reading: the redirect URLs the README asks you to register include separate callback paths for google-oauth, microsoft-oauth, github-oauth and sso under using-your-own-ui, plus three callback paths under using-hosted-authkit (basic, with-session and with-nextjs). The custom-UI path is where the OAuth provider plumbing is exposed, because that is the path where you are handling the callback yourself.

Installing the example and reaching a first sign-in

The README gives a four-step path from clone to a running app on port 3000. Dependencies install with npm:

npm install

The next step is credentials. Sign into the WorkOS dashboard, open API Keys, and copy the Client ID and the Secret Key. Rename .env.local.example to .env.local and fill in both values. The README shows the two keys exactly as they should appear:

WORKOS_CLIENT_ID="<your Client ID>"
WORKOS_API_KEY="<your Secret Key>"

Then register redirects in the dashboard under Redirects. The README lists six localhost URLs, and the ones you need depend on which example you are running. For the custom UI path:

http://localhost:3000/using-your-own-ui/sign-in/google-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/microsoft-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/github-oauth/callback
http://localhost:3000/using-your-own-ui/sign-in/sso/callback

For the hosted UI path the README lists three more: http://localhost:3000/using-hosted-authkit/basic/callback, .../with-session/callback and .../with-nextjs/callback. Finally, start the dev server and open the app:

npm run dev

What you should see at http://localhost:3000 is a Next.js app with routes into both example sets. If a callback fails, the first thing to check is whether that exact URL is registered in the dashboard, because the README treats the redirect list as a setup prerequisite rather than an optional step.

Where AuthKit stops being the right tool

The most concrete limitation is the one the package manifest states outright: "private": true and version 0.1.0. You cannot add this repository to a project as a dependency and receive updates through a package manager. Whatever you take from src/app, you copy by hand, and you own it from that moment.

The second constraint is the WorkOS account. The README's prerequisites section lists it as the only requirement and links to the dashboard signup. There is no documented path in this repository for running the authentication backend yourself, so a team that needs to keep identity data inside its own infrastructure will not find that option here. The README does not document self-hosting, and the redirect configuration flow assumes the WorkOS dashboard is the source of truth for allowed callback URLs.

Third, the README does not document rollback, migration away from WorkOS, or what happens to existing user sessions if you change the redirect configuration. If your team needs an exit plan written down before adopting an identity provider, this repository does not supply one.

Finally, treat the localhost redirect URLs as development-only. They are what the README tells you to register for running the example on port 3000. The README mentions pointing the hosted UI at a custom domain like auth.yourapp.com for production, but it does not walk through the production redirect set, so that step is on you and the WorkOS documentation.

How this compares with Supabase Auth and Better Auth

The search data around AuthKit shows people comparing it with Supabase and Better Auth, and the difference is architectural rather than a matter of feature lists.

Supabase Auth is part of a larger backend platform: authentication ships alongside a database and the rest of the Supabase stack. Choosing it usually means adopting that stack, or at least deciding how much of it you want. AuthKit, as this repository presents it, is authentication only. There is no database in the dependency list, and no data layer to adopt. If you already have a backend and only need the login surface, that narrower scope is the point.

Better Auth sits at the opposite end on hosting. It is a library you run inside your own application, so the auth logic and the user records live in your infrastructure. AuthKit's default path is the reverse: the hosted UI is served by WorkOS, and the headless path still calls WorkOS's User Management APIs rather than a local auth server. That is the real dividing line. If keeping identity data in your own database is a requirement, this repository is the wrong starting point, and the README offers no self-hosted alternative to fall back on.

The honest summary is that AuthKit trades infrastructure control for less code. The repository exists to show how little code that trade requires.

Dependencies, licence and what an upgrade costs you

The dependency list is short and worth reading before you copy anything. Runtime dependencies are @workos-inc/authkit-nextjs at ^4.3.0, @workos-inc/node at ^10.8.0, jose at ^5.2.3, next pinned to 16.2.12, and react and react-dom at ^19.2.0. Development dependencies cover TypeScript 5, ESLint 9 with eslint-config-next at 16.2.12, and the React and Node type packages.

Two things follow. First, the caret ranges on the WorkOS packages mean a fresh npm install can pull a newer minor version than whatever the maintainers last ran, while next and eslint-config-next are pinned exactly. Second, the maintenance surface is split: the example app changes rarely, but the two WorkOS packages underneath it are where the authentication behaviour actually lives, and those move on their own schedule. Upgrading the example means re-checking that the copied code still matches the current @workos-inc/authkit-nextjs API, not just bumping a version in package.json.

The licence is MIT, per the LICENSE file at the repository root. MIT is permissive and permits commercial use and modification, but this is a description of the licence text, not legal advice. One point worth noting for anyone reusing the code: the repository also contains a CODE_OF_CONDUCT.md, which governs participation in the project rather than use of the code. The last push to the default branch was on 2026-09-10.

Editorial conclusion

Adopt this repository as a reference, not as a dependency: it is a private, version 0.1.0 Next.js app whose two example routes show the hosted UI and the headless User Management APIs side by side. Teams already on WorkOS with a Next.js frontend will get the most from it, and anyone who needs a published, versioned auth package should look at @workos-inc/authkit-nextjs instead. Before building on it, verify in your own WorkOS dashboard that the six localhost redirect URLs listed in the README are registered, and confirm which of the two example directories matches the flow you intend to ship.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. workos/authkit on GitHub