Authentication

On This Page

How Sign-In Flows

Email/password, OAuth, and passkeys all hit one Next route: /api/auth/[...all]. Better Auth owns that route end to end.

After rate-limit and captcha checks pass, enrolled users get a 2FA challenge. Then the beforeSessionCreate hook picks the active organization and Better Auth sets the session cookie. By the time the dashboard renders, the session already knows which org is active.

Package Layout

What's Wired In

Eight pieces ship enabled. Each is a Better Auth plugin or a SyntaxKit layer on top of it.

How Sessions Work

Sessions are cookie-based and set by Better Auth. Your code treats them as opaque.

The kit extends the session with activeOrganizationId and impersonatedBy. On the user it adds role, twoFactorEnabled, ban state, lastActiveOrganizationId, and lastLoginMethod.

beforeSessionCreate fills activeOrganizationId when a session is created or refreshed. It prefers lastActiveOrganizationId if the user is still a member of that org; otherwise it uses the first org they belong to. When the user switches orgs with auth.api.setActiveOrganization, beforeSessionUpdate writes the new id to User.lastActiveOrganizationId so the next session picks it up.

Reading sessions on the server

Call auth.api.getSession({ headers }) in any React Server Component or route handler:

import { auth } from "@syntaxkit/auth";
import { headers } from "next/headers";
import { redirect } from "next/navigation";

const session = await auth.api.getSession({ headers: await headers() });
if (!session) redirect("/auth/login");

In oRPC handlers, the authorized procedure base does this for you and adds session and user to context. See API.

apps/web/proxy.ts checks for a session cookie with getSessionCookie(request) before the request reaches the route. That redirect sends unauthenticated traffic away from /dashboard and /api-reference.

Session cache and ban enforcement

Better Auth caches sessions in a signed cookie so most authenticated requests skip the database. Config lives in packages/auth/src/server.ts:

session: {
  cookieCache: {
    enabled: true,
    maxAge: 60,
  },
}

maxAge is the trade-off between fewer DB lookups and how fast a ban or revoke takes effect. While the cache is valid, auth.api.getSession returns the signed payload without hitting the database. auth.api.banUser can revoke server-side sessions immediately, but the cookie still satisfies getSession until maxAge elapses.

The kit closes that window on two surfaces:

• UI (immediate). Dashboard layouts call loadDashboardSession (apps/web/lib/dashboard-session.ts), which uses getSession with disableCookieCache: true and bounces on a missing session or isBanned(user). Banned or just-revoked users leave on the next /dashboard navigation. The admin layout reuses the same helper.
• API (bounded by maxAge). Direct /rpc/* and /api/* callers can see the cached payload for up to maxAge seconds after a ban. The default of 60 seconds is Better Auth's floor when fast revocation matters. Lower it for a tighter window (more DB lookups); raise it for fewer lookups; set maxAge: 0 to disable the cache.

isBanned(user) in packages/auth/src/utils.ts is the canonical ban check, including banExpires. Use it anywhere a cached session might still look valid.

Reading sessions in the browser

Client components use useSession from @syntaxkit/auth:

"use client";
import { useSession, signOut } from "@syntaxkit/auth";

export function HeaderUser() {
  const { data: session, isPending } = useSession();
  if (isPending) return null;
  return session
    ? <button onClick={() => signOut()}>Sign out</button>
    : <a href="/auth/login">Sign in</a>;
}

The same client exposes signIn.email, signIn.social, signUp.email, signOut, plus passkey and 2FA actions on their sub-namespaces.

Platform Admin Role

Platform admin is separate from organization roles. The Better Auth admin plugin adds role and ban state on User, plus impersonatedBy on Session.

isAdmin(role) is the canonical check. The requireAdmin middleware in API gates every procedure under the admin namespace. Admin-only pages like /dashboard/admin use the same helper at the layout level.

Bootstrap the first admin:

pnpm admin:bootstrap --email you@example.com

The script promotes a user only when no admin exists yet. After that, promote more admins with admin.setRole from the admin panel.

Email Flows

Five auth-related emails ship out of the box.

The first four are user-initiated and sent synchronously through oRPC mutations. A provider outage or send failure shows up in the UI (including an inline banner on the post-signup check-inbox screen). Better Auth hooks stay as best-effort fallbacks for direct API consumers; they are not the primary path for UI flows.

The welcome email is a SyntaxKit afterUserCreate hook. Failures there are logged and ignored on purpose.

See Email → Why The UI Flows Go Through oRPC Instead Of BA Hooks for the architecture rationale and failure-sentinel mapping.

Abuse Protection

Two layers, on purpose.

• Better Auth rate limits. Per-route limits in betterAuth({ rateLimit: ... }). Tight on /sign-in/email (5 per 10s), /sign-up/email (5 per minute), /request-password-reset (3 per minute), and the 2FA verify routes (3 per 10s). Default for everything else: 100 per minute. Limits widen under NODE_ENV=test so Vitest and Playwright do not fight the throttle. There is no opt-out env var, so production limits cannot be turned off by a leaky deploy template.
• Upstash email throttling. Layered on auth-email send paths via enforceAbusePolicy from packages/shared. Required in production (the boot doctor refuses to start without Upstash). Auto-bypassed in non-production when Upstash is unset, so pnpm dev can send verification emails on a fresh checkout. See Security → Abuse Protection.

Rate limits defend each endpoint. Email throttling defends the user/recipient no matter which endpoint the attacker hits.

Configuring OAuth Providers

GitHub and Google OAuth ship by default. Use Setup: GitHub OAuth or Setup: Google OAuth to create the provider app, register callback URLs, and set credentials.

Better Auth uses BETTER_AUTH_URL as the callback base when set; otherwise it falls back to NEXT_PUBLIC_APP_URL. Local and production setups use the origins shown in Setup.

For preview deployments, optional OAUTH_PROXY_SECRET routes OAuth through production:

1. Pin the callback base (BETTER_AUTH_URL when set, otherwise NEXT_PUBLIC_APP_URL) to the production origin in every environment.
2. Register the production callback with the provider.
3. Share the same secret (at least 32 characters) across production, preview, and local.
4. Allow preview or local return origins through AUTH_TRUSTED_ORIGINS.

This proxy secret is distinct from BETTER_AUTH_SECRET. See apps/web/.env.example for the full variable contract.

For providers beyond these two, see Adding A New OAuth Provider.

Adding A New OAuth Provider

Where To Go Next

Also useful: Organizations, Billing, and Setup.