Bootstrapping a new app with WorkOS AuthKit: Zero to authenticated in 5 minutes

Every auth tutorial starts the same way: install the SDK, set some env vars, wire up middleware, add a callback route, and, twenty minutes later, you finally see a login page (if it's your lucky day).

We have a way to bootstrap a new project in seconds instead, with running one command: npx workos@latest.

The 5 minute path

If you just want a working login in seconds, run:

  
npx workos@latest
  

The CLI Installer takes care of everything you would normally do manually:

1. Detects your framework: Identifies your framework and version from your project’s dependencies and file structure.
2. Authenticates your account: Opens your browser for secure WorkOS sign-in.
3. Configures your dashboard: Sets redirect URIs, CORS origins, and homepage URL automatically.
4. Installs the right SDK: Adds the correct AuthKit package for your framework.
5. Analyzes your project: Reads your project structure to understand routing, existing middleware, and configuration.
6. Creates routes and middleware: Writes OAuth callback routes, auth middleware/proxy, and provider wrappers.
7. Sets up environment variables: Writes API keys and configuration to .env.local
8. Validates the integration: Runs your build to verify everything compiles without errors.

WorkOS is free for up to 1 million users, so there's no billing detour to get through first.

That's it's, that's the whole quick start.

What follows is what the installer is doing for you, useful if you're on a framework the installer doesn't cover yet, or if you like to know what's landing in your repo.

The manual path (Next.js)

Next.js is the most common target, so we'll use it as the reference. The Rails and generic Node flows differ only in the SDK layer. The WorkOS dashboard steps are the same.

1. Install the SDK

The AuthKit Next.js SDK is @workos-inc/authkit-nextjs:

  
pnpm i @workos-inc/authkit-nextjs
  

2. Grab credentials

‍From the WorkOS Dashboard Overview page, copy your WORKOS_API_KEY and WORKOS_CLIENT_ID. Then set four env vars:

  
WORKOS_CLIENT_ID="client_..."
WORKOS_API_KEY="sk_test_..."
WORKOS_COOKIE_PASSWORD="<replace with a 32+ character secret>"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"
  

WORKOS_COOKIE_PASSWORD encrypts the session cookie and must be at least 32 characters. Generate one with openssl rand -base64 32. The NEXT_PUBLIC_ prefix makes the variable accessible in edge functions and proxy configurations, which matters for things like Vercel preview deployments.

3. Wrap your layout

‍AuthKitProvider is required to wrap your app layout and protects against auth edge cases. Check the AuthKit Next.js docs for the current import path:

  
import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <AuthKitProvider>{children}</AuthKitProvider>;
}
  

4. Add the proxy (or middleware)

‍Next.js renamed middleware.ts to proxy.ts starting in Next.js 16, so the file name depends on your Next.js version. Either way, the complete, out of the box solution uses the same authkitMiddleware function:

  
// proxy.ts (Next.js 16+), or middleware.ts (Next.js 15 and earlier)
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';

export default authkitMiddleware({
  middlewareAuth: {
    enabled: true,
    unauthenticatedPaths: ['/', '/pricing'],
  },
});

export const config = { matcher: ['/', '/dashboard/:page*'] };
  

WorkOS also offers a composable authkit method for apps where the proxy needs to do more than auth, and a page based auth mode as an alternative to the middleware auth mode shown here. See the AuthKit Next.js docs for those variants.

The matcher array declares which routes the proxy runs on, and any unauthenticated visitor to a protected route is redirected to the WorkOS hosted AuthKit login page.

5. Add sign in and callback routes

‍Two handlers, one to kick off sign in with getSignInUrl, one to handle the callback with handleAuth:

  
// app/login/route.ts
import { getSignInUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';

export const GET = async () => redirect(await getSignInUrl());
  

  
// app/callback/route.ts
import { handleAuth } from '@workos-inc/authkit-nextjs';

export const GET = handleAuth();
  

By default, handleAuth redirects to / after a successful sign in. Pass returnPathname to change that.

6. Read the user

‍In a server component, withAuth() returns the current user. Pass ensureSignedIn: true for routes where a session is mandatory:

  
const { user } = await withAuth({ ensureSignedIn: true });
  

One thing that trips people up: configure the sign out redirect in the WorkOS dashboard's Redirects section, or users hit an error after signing out.

Other frameworks

The dashboard steps above are framework agnostic. If you're on Rails, a generic Node server, or something else, the WorkOS credentials, redirect URIs, and OAuth provider setup are identical. Only the SDK layer changes. The CLI Installer detects your framework and writes the right integration code either way.

What you get once it's wired up

The reason to do this at all, beyond a working login, is what comes with the box. AuthKit ships as a drop in provider for user management, auth, social login, SSO, SCIM, and audit logs. Concretely:

• OAuth providers including Google, GitHub, Apple, and Microsoft
• Email and password with automatic strength enforcement and breach detection
• Magic auth (passwordless one time codes)
• MFA with TOTP
• Passkeys for biometric, passwordless sign in
• Enterprise SSO handling SAML/OIDC flows for Okta, Azure AD, and Google Workspace
• Directory Sync for Okta and Azure AD
• Audit Logs, Radar for real time bot and fraud protection, and Feature Flags

None of that requires application code changes. Toggle a provider in the dashboard, and it shows up on the hosted login page.

Where the five minutes actually goes

Timing this honestly: the installer runs in seconds. Copying two env vars from the dashboard takes a minute (the other two you set yourself). Adding the provider wrap, middleware, and two route handlers is another two or three minutes if you're typing it yourself. First successful sign in lands well inside the five minute mark.

If you're starting a new project today, run npx workos@latest and get on with building the actual product.