better-auth - D1 Adapter & Error Prevention Guide

📚 Docs: https://www.better-auth.com/changelogs

What's New in v1.3 (July 2025)

Major Features:

• SSO with SAML 2.0 - Enterprise single sign-on (moved to separate @better-auth/sso package)
• Multi-team support ⚠️ Breaking: teamId removed from member table, new teamMembers table required
• Additional fields - Custom fields for organization/member/invitation models
• Performance improvements and bug fixes

📚 Docs: https://www.better-auth.com/blog/1-3

Alternative: Kysely Adapter Pattern

If you prefer Kysely over Drizzle:

File: src/auth.ts

import { betterAuth } from "better-auth";
import { Kysely, CamelCasePlugin } from "kysely";
import { D1Dialect } from "kysely-d1";

type Env = {
  DB: D1Database;
  BETTER_AUTH_SECRET: string;
  // ... other env vars
};

export function createAuth(env: Env) {
  return betterAuth({
    secret: env.BETTER_AUTH_SECRET,

    // Kysely with D1Dialect
    database: {
      db: new Kysely({
        dialect: new D1Dialect({
          database: env.DB,
        }),
        plugins: [
          // CRITICAL: Required if using Drizzle schema with snake_case
          new CamelCasePlugin(),
        ],
      }),
      type: "sqlite",
    },

    emailAndPassword: {
      enabled: true,
    },

    // ... other config
  });
}

Why CamelCasePlugin?

If your Drizzle schema uses snake_case column names (e.g., email_verified), but better-auth expects camelCase (e.g., emailVerified), the CamelCasePlugin automatically converts between the two.

Framework Integrations

TanStack Start

⚠️ CRITICAL: TanStack Start requires the reactStartCookies plugin to handle cookie setting properly.

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { reactStartCookies } from "better-auth/react-start";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "sqlite" }),
  plugins: [
    twoFactor(),
    organization(),
    reactStartCookies(), // ⚠️ MUST be LAST plugin
  ],
});

Why it's needed: TanStack Start uses a special cookie handling system. Without this plugin, auth functions like signInEmail() and signUpEmail() won't set cookies properly, causing authentication to fail.

Important: The reactStartCookies plugin must be the last plugin in the array.

API Route Setup (/src/routes/api/auth/$.ts):

import { auth } from '@/lib/auth'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/auth/$')({
  server: {
    handlers: {
      GET: ({ request }) => auth.handler(request),
      POST: ({ request }) => auth.handler(request),
    },
  },
})

📚 Official Docs: https://www.better-auth.com/docs/integrations/tanstack

Available Plugins (v1.3+)

Better Auth provides plugins for advanced authentication features:

API Reference

Overview: What You Get For Free

When you call auth.handler(), better-auth automatically exposes 80+ production-ready REST endpoints at /api/auth/*. Every endpoint is also available as a server-side method via auth.api.* for programmatic use.

This dual-layer API system means:

• Clients (React, Vue, mobile apps) call HTTP endpoints directly
• Server-side code (middleware, background jobs) uses auth.api.* methods
• Zero boilerplate - no need to write auth endpoints manually

Time savings: Building this from scratch = ~220 hours. With better-auth = ~4-8 hours. 97% reduction.

Auto-Generated HTTP Endpoints

All endpoints are automatically exposed at /api/auth/* when using auth.handler().

Core Authentication Endpoints

Social OAuth Endpoints

Example OAuth flow:

// Client initiates
await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

// better-auth handles redirect to Google
// Google redirects back to /api/auth/callback/google
// better-auth creates session automatically

Plugin Endpoints

Two-Factor Authentication (2FA Plugin)

import { twoFactor } from "better-auth/plugins";

📚 Docs: https://www.better-auth.com/docs/plugins/2fa

Organization Plugin (Multi-Tenant SaaS)

import { organization } from "better-auth/plugins";

Organizations (10 endpoints):

Members (8 endpoints):

Invitations (7 endpoints):

Teams (8 endpoints):

Permissions & Roles (6 endpoints):

📚 Docs: https://www.better-auth.com/docs/plugins/organization

Admin Plugin

import { admin } from "better-auth/plugins";

📚 Docs: https://www.better-auth.com/docs/plugins/admin

Other Plugin Endpoints

Passkey Plugin (5 endpoints) - Docs:

• /passkey/add, /sign-in/passkey, /passkey/list, /passkey/delete, /passkey/update

Magic Link Plugin (2 endpoints) - Docs:

• /sign-in/magic-link, /magic-link/verify

Username Plugin (2 endpoints) - Docs:

• /sign-in/username, /username/is-available

Phone Number Plugin (5 endpoints) - Docs:

• /sign-in/phone-number, /phone-number/send-otp, /phone-number/verify, /phone-number/request-password-reset, /phone-number/reset-password

Email OTP Plugin (6 endpoints) - Docs:

• /email-otp/send-verification-otp, /email-otp/check-verification-otp, /sign-in/email-otp, /email-otp/verify-email, /forget-password/email-otp, /email-otp/reset-password

Anonymous Plugin (1 endpoint) - Docs:

• /sign-in/anonymous

JWT Plugin (2 endpoints) - Docs:

• /token (get JWT), /jwks (public key for verification)

OpenAPI Plugin (2 endpoints) - Docs:

• /reference (interactive API docs with Scalar UI)
• /generate-openapi-schema (get OpenAPI spec as JSON)

Server-Side API Methods (auth.api.*)

Every HTTP endpoint has a corresponding server-side method. Use these for:

• Server-side middleware (protecting routes)
• Background jobs (user cleanup, notifications)
• Admin operations (bulk user management)
• Custom auth flows (programmatic session creation)

Core API Methods

// Authentication
await auth.api.signUpEmail({
  body: { email, password, name },
  headers: request.headers,
});

await auth.api.signInEmail({
  body: { email, password, rememberMe: true },
  headers: request.headers,
});

await auth.api.signOut({ headers: request.headers });

// Session Management
const session = await auth.api.getSession({ headers: request.headers });

await auth.api.listSessions({ headers: request.headers });

await auth.api.revokeSession({
  body: { token: "session_token_here" },
  headers: request.headers,
});

// User Management
await auth.api.updateUser({
  body: { name: "New Name", image: "https://..." },
  headers: request.headers,
});

await auth.api.changeEmail({
  body: { newEmail: "[email protected]" },
  headers: request.headers,
});

await auth.api.deleteUser({
  body: { password: "current_password" },
  headers: request.headers,
});

// Account Linking
await auth.api.linkSocialAccount({
  body: { provider: "google" },
  headers: request.headers,
});

await auth.api.unlinkAccount({
  body: { providerId: "google", accountId: "google_123" },
  headers: request.headers,
});

Plugin API Methods

2FA Plugin:

// Enable 2FA
const { totpUri, backupCodes } = await auth.api.enableTwoFactor({
  body: { issuer: "MyApp" },
  headers: request.headers,
});

// Verify TOTP code
await auth.api.verifyTOTP({
  body: { code: "123456", trustDevice: true },
  headers: request.headers,
});

// Generate backup codes
const { backupCodes } = await auth.api.generateBackupCodes({
  headers: request.headers,
});

Organization Plugin:

// Create organization
const org = await auth.api.createOrganization({
  body: { name: "Acme Corp", slug: "acme" },
  headers: request.headers,
});

// Add member
await auth.api.addMember({
  body: {
    userId: "user_123",
    role: "admin",
    organizationId: org.id,
  },
  headers: request.headers,
});

// Check permissions
const hasPermission = await auth.api.hasPermission({
  body: {
    organizationId: org.id,
    permission: "users:delete",
  },
  headers: request.headers,
});

Admin Plugin:

// List users with pagination
const users = await auth.api.listUsers({
  query: {
    search: "john",
    limit: 10,
    offset: 0,
    sortBy: "createdAt",
    sortOrder: "desc",
  },
  headers: request.headers,
});

// Ban user
await auth.api.banUser({
  body: {
    userId: "user_123",
    reason: "Violation of ToS",
    expiresAt: new Date("2025-12-31"),
  },
  headers: request.headers,
});

// Impersonate user (for admin support)
const impersonationSession = await auth.api.impersonateUser({
  body: {
    userId: "user_123",
    expiresIn: 3600, // 1 hour
  },
  headers: request.headers,
});

When to Use Which

Example: Protected Route Middleware

import { Hono } from "hono";
import { createAuth } from "./auth";
import { createDatabase } from "./db";

const app = new Hono<{ Bindings: Env }>();

// Middleware using server-side API
app.use("/api/protected/*", async (c, next) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);

  // Use server-side method
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  // Attach to context
  c.set("user", session.user);
  c.set("session", session.session);

  await next();
});

// Protected route
app.get("/api/protected/profile", async (c) => {
  const user = c.get("user");
  return c.json({ user });
});

Discovering Available Endpoints

Use the OpenAPI plugin to see all endpoints in your configuration:

import { betterAuth } from "better-auth";
import { openAPI } from "better-auth/plugins";

export const auth = betterAuth({
  database: /* ... */,
  plugins: [
    openAPI(), // Adds /api/auth/reference endpoint
  ],
});

Interactive documentation: Visit http://localhost:8787/api/auth/reference

This shows a Scalar UI with:

• ✅ All available endpoints grouped by feature
• ✅ Request/response schemas with types
• ✅ Try-it-out functionality (test endpoints in browser)
• ✅ Authentication requirements
• ✅ Code examples in multiple languages

Programmatic access:

const schema = await auth.api.generateOpenAPISchema();
console.log(JSON.stringify(schema, null, 2));
// Returns full OpenAPI 3.0 spec

Quantified Time Savings

Building from scratch (manual implementation):

• Core auth endpoints (sign-up, sign-in, OAuth, sessions): 40 hours
• Email verification & password reset: 10 hours
• 2FA system (TOTP, backup codes, email OTP): 20 hours
• Organizations (teams, invitations, RBAC): 60 hours
• Admin panel (user management, impersonation): 30 hours
• Testing & debugging: 50 hours
• Security hardening: 20 hours

Total manual effort: ~220 hours (5.5 weeks full-time)

With better-auth:

• Initial setup: 2-4 hours
• Customization & styling: 2-4 hours

Total with better-auth: 4-8 hours

Savings: ~97% development time

Key Takeaway

better-auth provides 80+ production-ready endpoints covering:

• ✅ Core authentication (20 endpoints)
• ✅ 2FA & passwordless (15 endpoints)
• ✅ Organizations & teams (35 endpoints)
• ✅ Admin & user management (15 endpoints)
• ✅ Social OAuth (auto-configured callbacks)
• ✅ OpenAPI documentation (interactive UI)

You write zero endpoint code. Just configure features and call auth.handler().

Known Issues & Solutions

Issue 1: "d1Adapter is not exported" Error

Problem: Code shows import { d1Adapter } from 'better-auth/adapters/d1' but this doesn't exist.

Symptoms: TypeScript error or runtime error about missing export.

Solution: Use Drizzle or Kysely instead:

// ❌ WRONG - This doesn't exist
import { d1Adapter } from 'better-auth/adapters/d1'