When a verification succeeds, the browser SDKs can remember it, so the user doesn’t have to verify again on every page. This page explains how that works and when to change it. It applies to every framework.

SDK-managed sessions

This is the default. When the browser sees a verification succeed, it calls your app’s /api/authbound/session route. That route:
  1. checks the verification was started in this same browser,
  2. fetches the signed result from Authbound with your secret key, and
  3. sets an encrypted, HttpOnly session cookie.
Route protection, such as the Next.js middleware or Nuxt’s protectedRoutes, reads that cookie. The server SDK router or handler for your framework adds the session route for you. The session cookie is a convenience for your pages. For anything that must hold up later, such as marking an account verified, record the result on your server from a webhook or signed result.

Manual sessions

Switch to manual mode if:
  • your app already has its own sessions and you’d rather record the verification there,
  • your backend doesn’t expose /api/authbound/session, or
  • you need to support in-app browsers that lack the Web Locks API (see below).
In manual mode, the browser still shows progress, but the SDK doesn’t set a cookie. Record the result yourself from a webhook or signed result.
<AuthboundProvider
  publishableKey={publishableKey}
  policyId={policyId}
  sessionMode="manual"
>

Several tabs at once

The SDK serializes verification creation and session finalization across same-origin tabs. It does this with the browser’s Web Locks API. Every modern browser supports it, but some in-app webviews don’t. Without it, the SDK stops with session_coordination_unsupported rather than risk two sessions racing. Web Locks only work within one origin. If several of your subdomains share a session cookie, use manual mode and coordinate sessions on your server.

Time limits

WhatLastsWhat happens after
A verification and its client token15 minutes by defaultStatus becomes expired. Start a new verification.
The SDK’s pending-verification cookie10 minutesThe SDK can’t set the session cookie and fails with VERIFICATION_BINDING_REQUIRED.
So if a user spends more than 10 minutes in their wallet, the verification can still succeed, but the browser session can’t be created. Ask them to start again, or use manual mode and record the result from a webhook.

Behind a proxy

Before setting the session cookie, the session route checks that the request came from your own site. Behind a load balancer or in a container, the URL your app sees can differ from the one users visit, and that check fails. Tell Authbound your public origin with allowedOrigins. In Nuxt, it’s a module option. For Next.js, Express and Hono, it goes in the server config:
{
  // ...the rest of your Authbound server config
  allowedOrigins: ["https://your-app.example"],
}
With Next.js, Express or Hono, if your proxy sets Forwarded or X-Forwarded-* headers, you can set trustProxy: true instead. Only do this when infrastructure you control sets those headers. Otherwise anyone can forge them.