The Next.js quickstart gets a verification working with the least configuration. This page covers what you add once you’re building for real. Each section stands on its own, so skip the ones you don’t need.

Routes the handler adds

createAuthboundHandlers serves these routes under app/api/authbound/[[...authbound]]:
RouteWhat it does
POST /api/authbound/verificationStarts a verification and returns the wallet handoff to the browser.
GET /api/authbound/statusReads the SDK session cookie.
POST /api/authbound/sessionSets the session cookie after a successful verification.
POST /api/authbound/webhookReceives webhooks, if you enable them.
DELETE /api/authboundSigns the user out by clearing the session cookie.
Only the server talks to Authbound with your secret key. The browser talks to these routes, and to Authbound with its per-verification client token.

Choose the catch-all route

The optional [[...authbound]] route matches both the base /api/authbound path and its subpaths, so DELETE /api/authbound reaches the sign-out handler. If your app uses a required [...authbound] route, it only matches subpaths. Send DELETE /api/authbound/signout, or mount createSignOutHandler(config) as DELETE in a dedicated app/api/authbound/route.ts file. Keep the same server configuration and session secret as the verification handlers.

Receive webhooks

Add your webhook signing secret and tell the handler which path receives webhooks:
app/api/authbound/[[...authbound]]/route.ts
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!,
  routes: {
    protected: [],
    verify: "/verify",
    callback: "/api/authbound/webhook",
  },
});
Then add https://your-app.example/api/authbound/webhook as a webhook endpoint in the dashboard. Webhooks and results covers what to do with each event.

Run behind a proxy

If your app runs behind a load balancer or in a container, set your public origin so the session route accepts requests from it:
createAuthboundHandlers({
  // ...
  allowedOrigins: [process.env.NEXT_PUBLIC_APP_URL!],
});
Browser sessions explains why, and when trustProxy is the better choice.

Use your own sessions

By default, the SDK sets its own session cookie when a verification succeeds, and withAuthbound middleware reads it. To record verifications in your own session system instead, set sessionMode="manual" on AuthboundProvider. Browser sessions covers both modes, what happens with several tabs open, and the time limits.

Set EUDI wallet options

Some EUDI flows need extra settings, such as a response mode or the origins the wallet should expect. These are security-sensitive, so the browser can’t set them. Configure them on a server route instead. From SDK 0.5.0, the catch-all handler takes them and sends them with every verification it creates. A customer-controlled EUDI verifier starts a wallet request only for this exact HAIP request; with any other combination the verification is created but no wallet can answer it:
app/api/authbound/[[...authbound]]/route.ts
import { createAuthboundHandlers } from "@authbound/nextjs/server";
import { authboundConfig } from "@/authbound.config";

export const { GET, POST, DELETE } = createAuthboundHandlers(authboundConfig, {
  providerOptions: {
    eudi: {
      profile: "haip",
      responseMode: "direct_post.jwt",
      jarMode: "by_reference",
      requestUriMethod: "get",
    },
  },
});
To set them for one flow only, or with an earlier SDK, add a dedicated verification route:
app/api/authbound/verification/route.ts
import { asPolicyId, 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://your-app.example"],
    },
  },
});
Next.js routes a request to the most specific file, so this route takes over /api/authbound/verification from the catch-all. From a server action or other server code, pass the same providerOptions to createVerification from @authbound/nextjs/server.

Add station routes

Stations are for in-person verification, such as a QR code at a venue entrance. They’re enabled per organization. If you don’t see Stations in your dashboard, contact us.

Station UI and runtime mode

@authbound/react and @authbound/vue export StationEntry, StationEntryDisplay and StationOperatorConsole, plus their station hooks or composables. Use the React exports for a Next.js client component. In Nuxt, import station components and composables explicitly from @authbound/vue; the module does not auto-import station UI. Station components and hooks accept runtimeMode and runtimeBaseUrl. The default runtimeMode="direct" uses tokenized Gateway endpoints under /v1/stations/public; with neither runtimeBaseUrl nor gatewayBaseUrl supplied, the origin is https://api.authbound.io. Set runtimeMode="proxy" when using the same-origin station routes below. With neither runtimeBaseUrl nor gatewayBaseUrl supplied, proxy mode uses relative /api/authbound/stations/... URLs, so it does not require accessing window during server rendering. Display and operator operations still require their scoped display/grant tokens; routing through a proxy does not bypass those checks. Keep server secret keys out of browser props. SDK exports do not enable Stations for an organization. The Nuxt module adds station routes automatically. In Next.js, add one route file per endpoint:
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 pass station tokens through to Authbound. They don’t use your secret key. Each one reads AUTHBOUND_API_URL if set, or you can pass gatewayUrl.

Before you go live

  • Switch to live keys (sk_live_, pk_live_).
  • AUTHBOUND_SECRET_KEY and AUTHBOUND_SESSION_SECRET are only in server environment variables.
  • Webhooks are enabled, and your handler records results idempotently.
  • Anything that grants access checks a webhook or signed result, not just the browser.
  • allowedOrigins is set if your app runs behind a proxy.
  • trustProxy is only on if your own infrastructure sets the forwarded headers.

Use a staging or self-hosted gateway

Set AUTHBOUND_API_URL for server handlers. Pass the same origin as gatewayUrl to AuthboundProvider; for Next.js client code, use NEXT_PUBLIC_AUTHBOUND_API_URL. The browser cannot read the server-only variable. Point both sides at the same environment.
<AuthboundProvider
  publishableKey={process.env.NEXT_PUBLIC_AUTHBOUND_PK!}
  policyId={policyId}
  gatewayUrl={process.env.NEXT_PUBLIC_AUTHBOUND_API_URL}
>
  {children}
</AuthboundProvider>