Quickstarts

Next.js quickstart

Wire OrthID into a Next.js App Router app. You will add the provider, middleware, a sign-in page, and server-side session reads, then protect a route.

Preview

The OrthID SDKs and public API are in active development and available to design partners. The samples below are illustrative of the planned API. Talk to us to get early access.

This guide assumes the App Router (Next.js 13.4+). If you have not created a project and set your keys yet, do the five-minute Quickstart first, then come back. You should already have NEXT_PUBLIC_ORTHID_PUBLISHABLE_KEY, ORTHID_SECRET_KEY, and ORTHID_REGION in your environment.

1. Get the Next.js package

The @orthid/nextjs package adds the provider, middleware, and server helpers on top of the core SDK. Request preview access, and you will receive install instructions for your design-partner build.

2. Wrap your app in the provider

Add <OrthIDProvider> to your root layout. It reads the publishable key, manages the session in the browser, and makes the OrthID hooks and components available everywhere in the tree.

app/layout.tsx (planned API)

import { OrthIDProvider } from "@orthid/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <OrthIDProvider
      publishableKey={process.env.NEXT_PUBLIC_ORTHID_PUBLISHABLE_KEY!}
    >
      <html lang="en">
        <body>{children}</body>
      </html>
    </OrthIDProvider>
  );
}

3. Add the middleware

The middleware verifies the session on every matched request and keeps the token fresh. Create middleware.ts at the project root (next to app/).

middleware.ts (planned API)

import { orthidMiddleware } from "@orthid/nextjs";

export default orthidMiddleware();

export const config = {
  // Run on app routes and APIs, skip Next internals and static files.
  matcher: ["/((?!_next|.*\\..*).*)", "/api/(.*)"],
};

Note

The middleware only verifies and refreshes the session; it does not block anonymous traffic by default. You decide which routes require a signed-in actor in step 6.

4. Add a sign-in route

Drop the <SignIn/> component on a route. It renders the full authentication flow (passkeys, MFA, SSO) and handles the redirect back into your app on success. No extra wiring required.

app/sign-in/page.tsx (planned API)

import { SignIn } from "@orthid/nextjs";

export default function SignInPage() {
  return (
    <main className="grid min-h-screen place-items-center">
      <SignIn afterSignInUrl="/dashboard" />
    </main>
  );
}

5. Read the user server-side

In a Server Component (or route handler), call currentUser() to read the signed-in actor. Because the middleware already verified the session, this is a fast, local lookup with no extra round trip.

app/dashboard/page.tsx (planned API)

import { currentUser } from "@orthid/nextjs/server";

export default async function Dashboard() {
  const user = await currentUser();

  if (!user) {
    return <p>You are signed out.</p>;
  }

  return <h1>Welcome back, {user.firstName}.</h1>;
}

6. Protect a route

To require a signed-in actor, read the auth state and redirect when it is missing. Use auth() for a lightweight check that returns the actor id and session without loading the full user record.

app/settings/page.tsx (planned API)

import { redirect } from "next/navigation";
import { auth } from "@orthid/nextjs/server";

export default async function Settings() {
  const { actorId } = await auth();

  if (!actorId) {
    redirect("/sign-in");
  }

  return <h1>Account settings</h1>;
}

Tip

Prefer to guard whole route segments in one place? Pass a matcher to orthidMiddleware with a list of protected paths and it will redirect anonymous requests for you, before they reach your components.

Next steps

<SignIn/> reference for props, hosted vs embedded modes, and theming.
Sessions to understand what the middleware verifies and refreshes.