Horizon
GuidesSign-in and OAuth

Test WorkOS AuthKit locally with an HTTPS redirect URI

Test WorkOS AuthKit sign-in on localhost with a Horizon tunnel, using a stable HTTPS redirect URI that WorkOS accepts in a production environment.

Sign in with WorkOS AuthKit on your laptop, with an HTTPS redirect URI that WorkOS accepts outside localhost.

WorkOS production environments don't accept http or localhost redirect URIs. Sandbox environments do. A Horizon tunnel gives you an https URL that works in either.

Before you begin

  • Node.js 18 or later
  • A Horizon account and the CLI (see Getting started)
  • A reserved subdomain for -s. Reserve one on the Subdomains page.
  • A WorkOS account with an application, and a Next.js app that uses AuthKit

Start a tunnel

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so the redirect URI you save in WorkOS would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

hrzn tunnel http://localhost:3000 -s my-app
Output
HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

Your public URL is https://my-app.hrzn.run. Keep this terminal open.

The first time you open the URL in a browser, Horizon shows a Before you continue page. Select Continue to site. You see it once every 7 days per IP address, so the redirect back from WorkOS won't surprise you later.

Add the redirect URI in WorkOS

  1. Open the WorkOS Dashboard and select the environment you test in.
  2. Open Applications, select your application, and open the Redirects tab.
  3. Add https://my-app.hrzn.run/auth/callback as a redirect URI. Make it the default redirect URI if no other one is set.
  4. Set Initiate login URI to https://my-app.hrzn.run/sign-in.

The path must match the route in your app. The next step creates both routes.

Set the app environment variables

Install the AuthKit SDK for Next.js.

npm install @workos-inc/authkit-nextjs @workos-inc/node

AuthKit reads the redirect URI from NEXT_PUBLIC_WORKOS_REDIRECT_URI. Set it to the public URL. If you leave it at http://localhost:3000/callback, the sign-in flow sends WorkOS a localhost address.

The cookie password must be at least 32 characters. Generate one with openssl rand -base64 24.

.env.local
WORKOS_CLIENT_ID="client_..."
WORKOS_API_KEY="sk_test_..."
WORKOS_COOKIE_PASSWORD="<your password>"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="https://my-app.hrzn.run/auth/callback"

Create the callback route.

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

export const GET = handleAuth();

Create the route that starts sign-in.

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

export const GET = async () => {
  const signInUrl = await getSignInUrl();
  return redirect(signInUrl);
};

Add the AuthKit proxy. On Next.js 16 and later, the file is proxy.ts.

proxy.ts
import { authkitProxy } from "@workos-inc/authkit-nextjs";

export default authkitProxy();

export const config = { matcher: ["/", "/admin"] };

On Next.js 15 and earlier, create middleware.ts with authkitMiddleware instead of authkitProxy.

Start the app on port 3000. Restart it after you edit .env.local.

npm run dev

Sign in through the public URL

Open https://my-app.hrzn.run/sign-in, not localhost:3000. Start from the public URL so the browser, WorkOS and your app agree on the host.

Check it works

AuthKit shows its hosted sign-in page. After you sign in, WorkOS redirects the browser to https://my-app.hrzn.run/auth/callback.

Your Horizon terminal prints a GET line for /auth/callback. A 3xx status means your app redirected you onward. If the line shows a 4xx or 5xx, see Troubleshooting.

Troubleshooting

The callback goes to localhost

NEXT_PUBLIC_WORKOS_REDIRECT_URI still holds the localhost value, or the dev server didn't pick up the change. Horizon sets the Host header to localhost:3000 and sends the public host in X-Forwarded-Host, so a framework that builds the redirect URI from Host gets localhost. Set the variable to https://my-app.hrzn.run/auth/callback and restart npm run dev.

WorkOS rejects the redirect URI

  • Check that the redirect URI in the Redirects tab matches NEXT_PUBLIC_WORKOS_REDIRECT_URI exactly, including the path.
  • In a production environment, WorkOS doesn't accept http or localhost redirect URIs. Use the https://my-app.hrzn.run address.
  • Check that you edited the environment you sign in with. Sandbox and production keep separate redirect URIs.

The tunnel URL changed

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your app

  • Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
  • Check that your app listens on port 3000.

Next steps

Test Supabase Auth redirects and OAuth locally

Test Supabase Auth sign-in and OAuth providers on localhost with a Horizon tunnel, and set the Site URL and Redirect URLs once.

Test Login with Amazon locally

Test Login with Amazon on localhost by registering a stable HTTPS Allowed Return URL from a Horizon tunnel.

On this page

Before you beginStart a tunnelAdd the redirect URI in WorkOSSet the app environment variablesSign in through the public URLCheck it worksTroubleshootingThe callback goes to localhostWorkOS rejects the redirect URIThe tunnel URL changedNothing reaches your appNext steps