Routes the handler adds
createAuthboundHandlers serves these routes under app/api/authbound/[[...authbound]]:
| Route | What it does |
|---|---|
POST /api/authbound/verification | Starts a verification and returns the wallet handoff to the browser. |
GET /api/authbound/status | Reads the SDK session cookie. |
POST /api/authbound/session | Sets the session cookie after a successful verification. |
POST /api/authbound/webhook | Receives webhooks, if you enable them. |
DELETE /api/authbound | Signs the user out by clearing the session cookie. |
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
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:trustProxy is the better choice.
Use your own sessions
By default, the SDK sets its own session cookie when a verification succeeds, andwithAuthbound 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
app/api/authbound/verification/route.ts
/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
app/api/authbound/stations/[stationId]/display/route.ts
app/api/authbound/stations/[stationId]/display/events/sse/route.ts
app/api/authbound/stations/[stationId]/operator/route.ts
app/api/authbound/stations/[stationId]/operator/events/sse/route.ts
app/api/authbound/stations/[stationId]/verifications/[verificationId]/disclosure/route.ts
AUTHBOUND_API_URL if set, or you can pass gatewayUrl.
Before you go live
- Switch to live keys (
sk_live_,pk_live_). -
AUTHBOUND_SECRET_KEYandAUTHBOUND_SESSION_SECRETare 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.
-
allowedOriginsis set if your app runs behind a proxy. -
trustProxyis only on if your own infrastructure sets the forwarded headers.
Use a staging or self-hosted gateway
SetAUTHBOUND_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.