Authentication

Authentication is integrated end to end with Better Auth: email/password with required verification, password reset, GitHub and Google OAuth, sessions, and an admin plugin for roles.

What it provides

• Email/password registration with required email verification.
• Password reset by email.
• GitHub and Google OAuth, with account linking.
• Database-backed sessions (the session table).
• An admin plugin with a role field for role-based access.

Important files

Server setup

src/lib/auth.ts wires Better Auth to the Drizzle adapter and Resend:

• emailAndPassword.enabled with requireEmailVerification: true — new users must verify before they can log in.
• emailVerification.sendOnSignUp: true — verification email is sent on registration, delivered through sendEmail (Resend).
• sendResetPassword — password-reset emails use the ForgotPassword template.
• socialProviders.github and socialProviders.google — read their client ID/secret from the environment.
• account.accountLinking.enabled: true — links OAuth accounts to an existing user by email.
• plugins: [admin()] — adds the admin plugin and the role field.

The route handler

All auth endpoints are served by one catch-all route:

import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { GET, POST } = toNextJsHandler(auth);

Auth pages

OAuth providers

src/lib/auth.ts always registers GitHub and Google, and OAuthButtons renders a button for each. The provider credentials come from GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET and GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — see Environment Variables.

When registering a provider, set the callback URL to {BETTER_AUTH_URL}/api/auth/callback/{provider}, e.g. http://localhost:3000/api/auth/callback/github.

Sessions and roles

• Client: useSession() from src/lib/auth-client.ts reads the current session in Client Components.

• Server: read the session authoritatively in route handlers and Server Components:

  const session = await auth.api.getSession({ headers: await headers() });

• Admin: the user.role field (default "user") gates admin access. The admin users API enforces it:

  if (session.user.role !== "admin") {
    return NextResponse.json({ success: false, error: "Forbidden" }, { status: 403 });
  }

Verify

• Register a new account at /auth/login → register.
• Receive and click the verification email (requires Resend).
• Log in with the verified account.
• Sign in with GitHub and Google (if configured).
• Request a password reset and set a new password.
• Log out.
• Visit /dashboard while logged out → redirected to login with a callbackUrl.

Production notes

• Set a stable, secret BETTER_AUTH_SECRET (rotating it invalidates sessions).
• Set BETTER_AUTH_URL to your canonical HTTPS URL and register matching OAuth callback URLs.
• Keep authoritative session/role checks in every protected API and mutation — do not rely on proxy.ts.

Related pages