Next.js

Use @authbound/nextjs when you want the shortest path from a Next.js app to a wallet verification screen.

Install

pnpm add @authbound/nextjs

Environment

.env.local

AUTHBOUND_SECRET_KEY=sk_test_...
AUTHBOUND_SESSION_SECRET=replace-with-a-random-32-byte-secret
AUTHBOUND_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_AUTHBOUND_PK=pk_test_...
NEXT_PUBLIC_AUTHBOUND_POLICY_ID=pol_kyc_basic_eudi_v1
NEXT_PUBLIC_APP_URL=https://your-app.example

Use a preset policy ID such as pol_kyc_basic_eudi_v1, or copy one of your own from the Authbound dashboard. The browser SDK sends this policy ID to the server route when it creates a verification. See SDKs and frameworks for the complete preset list.

Server route

Create app/api/authbound/[...authbound]/route.ts.

app/api/authbound/[...authbound]/route.ts

import { createAuthboundHandlers } from "@authbound/nextjs/server";

export const { GET, POST, DELETE } = createAuthboundHandlers({
  apiKey: process.env.AUTHBOUND_SECRET_KEY!,
  publishableKey: process.env.NEXT_PUBLIC_AUTHBOUND_PK!,
  secret: process.env.AUTHBOUND_SESSION_SECRET!,
  webhookSecret: process.env.AUTHBOUND_WEBHOOK_SECRET!,
  allowedOrigins: [process.env.NEXT_PUBLIC_APP_URL!],
  routes: {
    protected: [],
    verify: "/verify",
    callback: "/api/authbound/webhook",
  },
});

The handler exposes the SDK routes under /api/authbound: verification creation, same-origin session finalization, status, webhook callback, and sign out. It calls https://api.authbound.io/v1/verifications from your server and sends your secret key as X-Authbound-Key. During session finalization it checks the pending browser binding and fetches the signed verification result with your secret key before setting the SDK cookie.

Provider

Create app/authbound-provider.tsx.

app/authbound-provider.tsx

"use client";

import {
  asPolicyId,
  AuthboundProvider,
} from "@authbound/nextjs/client";
import type { ReactNode } from "react";

const policyId = asPolicyId(process.env.NEXT_PUBLIC_AUTHBOUND_POLICY_ID!);

export function AuthboundProviders({ children }: { children: ReactNode }) {
  return (
    <AuthboundProvider
      publishableKey={process.env.NEXT_PUBLIC_AUTHBOUND_PK!}
      policyId={policyId}
    >
      {children}
    </AuthboundProvider>
  );
}

Wrap your app.

app/layout.tsx

import "@authbound/nextjs/styles.css";
import { AuthboundProviders } from "./authbound-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthboundProviders>{children}</AuthboundProviders>
      </body>
    </html>
  );
}

Verification page

app/verify/page.tsx

"use client";

import {
  asPolicyId,
  VerificationWall,
} from "@authbound/nextjs/client";

const policyId = asPolicyId(process.env.NEXT_PUBLIC_AUTHBOUND_POLICY_ID!);

export default function VerifyPage() {
  return (
    <VerificationWall
      policyId={policyId}
      title="Verify your age"
      description="Use your EU Digital Identity Wallet to continue."
      onVerified={({ verificationId, status }) => {
        console.log("Verified", verificationId, status);
      }}
    >
      <main>
        <h1>Verified</h1>
        <p>You can now continue.</p>
      </main>
    </VerificationWall>
  );
}

Open /verify, start the flow, and scan the QR code with a compatible wallet.

Session mode

By default, AuthboundProvider uses sessionMode="sdk". After verified status, the browser calls POST /api/authbound/session; the route checks the pending browser binding, fetches the signed result with your secret key, and sets the SDK session cookie. SDK-managed sessions require navigator.locks. Same-origin tabs serialize verification creation and session finalization under a lock keyed by the resolved endpoint origin. If you need to support a browser or embedded webview without Web Locks, use sessionMode="manual" and create the trusted session on your server. If your backend only creates verifications and does not expose /api/authbound/session, set sessionMode="manual" on AuthboundProvider and persist trusted state with your own webhook or signed-result flow.

Station BFF routes

Unlike @authbound/nuxt, the Next.js package does not auto-register station routes. Add one App Router route file per endpoint when you build station entry or operator flows with @authbound/react station components.

app/api/authbound/stations/[stationId]/entry/route.ts

import { createStationEntryRoute } from "@authbound/nextjs/server";

export const POST = createStationEntryRoute();

app/api/authbound/stations/[stationId]/display/route.ts

import { createStationDisplayRoute } from "@authbound/nextjs/server";

export const GET = createStationDisplayRoute();

app/api/authbound/stations/[stationId]/display/events/sse/route.ts

import { createStationDisplayEventsRoute } from "@authbound/nextjs/server";

export const GET = createStationDisplayEventsRoute();

app/api/authbound/stations/[stationId]/operator/route.ts

import { createStationOperatorRoute } from "@authbound/nextjs/server";

export const GET = createStationOperatorRoute();

app/api/authbound/stations/[stationId]/operator/events/sse/route.ts

import { createStationOperatorEventsRoute } from "@authbound/nextjs/server";

export const GET = createStationOperatorEventsRoute();

app/api/authbound/stations/[stationId]/verifications/[verificationId]/disclosure/route.ts

import { createStationDisclosureRoute } from "@authbound/nextjs/server";

export const GET = createStationDisclosureRoute();

These routes proxy tokenized station requests to Gateway without attaching your project secret key. Each factory accepts gatewayUrl and otherwise uses AUTHBOUND_API_URL or https://api.authbound.io.

EUDI provider options

For EUDI wallet flows, configure providerOptions on a server-owned verification route. The browser may send a provider preference such as "eudi", but SDK handlers ignore client-supplied providerOptions. The catch-all createAuthboundHandlers route does not accept providerOptions. Use createVerificationRoute when you want EUDI settings on the verification creation endpoint:

app/api/authbound/verification/route.ts

import { asPolicyId } from "@authbound/core";
import { createVerificationRoute } from "@authbound/nextjs/server";

export const POST = createVerificationRoute({
  policyId: asPolicyId(process.env.NEXT_PUBLIC_AUTHBOUND_POLICY_ID!),
  providerOptions: {
    eudi: {
      responseMode: "dc_api.jwt",
      expectedOrigins: ["https://merchant.example"],
    },
  },
});

Point AuthboundProvider at that route with verificationEndpoint="/api/authbound/verification", or pass providerOptions to a server-side createVerification call.

Production checklist

Keep AUTHBOUND_SECRET_KEY server-only.
Use NEXT_PUBLIC_AUTHBOUND_PK as the browser-safe publishable key for AuthboundProvider and SDK server handlers.
Use a long random AUTHBOUND_SESSION_SECRET; the SDK uses it for HttpOnly session cookies.
Set allowedOrigins to your public app origin when the route runs behind a proxy or container URL.
Set trustProxy: true only when Forwarded or X-Forwarded-* headers are supplied by infrastructure you control.
Add webhooks or signed result lookups for backend reconciliation.
Store the final verified state in your own user or session model when the decision must outlive the browser flow.
Fetch signed results on the server for high-trust decisions.

Route protection

Protect pages after verification completes.

Webhooks

Sync results to your backend.

Start here

Identity verification

Credential issuance

AI

Install

Environment

Server route

Provider

Verification page

Session mode

Station BFF routes

EUDI provider options

Production checklist

Route protection

Webhooks

​Install

​Environment

​Server route

​Provider

​Verification page

​Session mode

​Station BFF routes

​EUDI provider options

​Production checklist

Route protection

Webhooks

Install

Environment

Server route

Provider

Verification page

Session mode

Station BFF routes

EUDI provider options

Production checklist