← Integration guides

Web frontend + your own backend (BFF)

Your frontend never talks to this platform. Not React, not Vue, not Svelte, not Angular, not plain JS — whichever you use, the actual OAuth work (PKCE, the redirect, the code-for-token exchange) belongs entirely to your own backend — see the Django, Node.js, Laravel, or Go guide for that half. This is why there's one page here, not five — the frontend's own job in this pattern is small and identical regardless of framework.

What your frontend actually does

  1. Renders a login link — a plain <a>, pointing at your own backend's login route (e.g. /auth/login), never at accounts.onehux.com directly.
  2. Your backend handles everything from there — the PKCE pair, the redirect to this platform, the callback, the token exchange — and finishes by setting its own session (a cookie your frontend's own domain controls).
  3. Your frontend calls your own backend's API for user data (e.g. GET /api/me), which your backend fills in by calling this platform's /api/v1/oauth/userinfo/ server-side — your frontend never holds, sees, or handles a OneHux access token at all.

Why — the token never belongs in the browser

A token held in localStorage, a JS variable, or any client-JS-reachable state is one XSS bug away from being exfiltrated — there is no way to make client-side JS hold a bearer credential safely. An httpOnly cookie set by your own backend is unreadable by any JS at all, on either side, which is the entire point. This is the exact pattern this dashboard you're reading right now uses on itself — not a theoretical recommendation, a real, currently-running example of it.

Example — a login link and an authenticated fetch

<!-- Any framework — this is the entire frontend-side surface of this integration -->
<a href="/auth/login">Sign in</a>
// Your frontend calling YOUR OWN backend — never OneHux directly
const res = await fetch('/api/me', { credentials: 'include' });
const user = await res.json(); // whatever shape your own backend chooses to return

If your frontend framework has its own server layer

A meta-framework with its own server runtime (SvelteKit, Next.js, Nuxt, Remix) can play the "backend" role itself — that server-side half (its load functions/API routes/server actions) follows the same underlying pattern as the Node.js guide, via the same @onehux/sso package. The client-side half — the part actually running in the browser — is still exactly what this page describes: it never touches a token, never calls this platform directly.

SvelteKit, Next.js, and Nuxt each get a dedicated integration built for that framework's own conventions, not a generic Express-shaped stand-in: @onehux/sso/sveltekit (a hooks.server.ts hook for proactive token refresh, plus login/callback/logout/backchannel-logout handlers for SvelteKit's file-based routing), @onehux/sso/next (App Router middleware and Route Handlers — deliberately Edge-runtime-safe for the middleware, since Route Handlers already default to the Node.js runtime), and @onehux/sso/nuxt (Nitro/H3 server middleware and file-routed event handlers). See the package README for the full setup of each.

This is also where the two patterns can genuinely split. If your meta-framework's server IS the thing that talks to OneHux directly, it's the OAuth client/BFF — the adapters above. But if a different, separate backend (Django, Go, Laravel, another Node service) does the actual OAuth exchange and your meta-framework's server only ever receives an already-issued token from it, your meta-framework's server is itself a resource server in that relationship — see the "Resource server" section on whichever backend guide holds the real OAuth client role.

← React Native