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:
- checks the verification was started in this same browser,
- fetches the signed result from Authbound with your secret key, and
- sets an encrypted, HttpOnly session cookie.
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).
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 withsession_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
| What | Lasts | What happens after |
|---|---|---|
| A verification and its client token | 15 minutes by default | Status becomes expired. Start a new verification. |
| The SDK’s pending-verification cookie | 10 minutes | The SDK can’t set the session cookie and fails with VERIFICATION_BINDING_REQUIRED. |
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 withallowedOrigins. In Nuxt, it’s a module option. For Next.js, Express and Hono, it goes in the server config:
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.