Better Auth Best Practices

Comprehensive reference for the Better Auth framework. Covers configuration, security hardening, rate limiting, session management, plugins, and production deployment patterns.

Canonical docs: better-auth.com/docs Source: Synthesized from better-auth/skills (official upstream) + Grove production experience.

When to Activate

• Configuring or modifying Better Auth server/client setup
• Auditing auth security (pair with

  raccoon-audit

  ,

  turtle-harden

  )
• Adding or configuring rate limiting
• Setting up session management, cookie caching, or secondary storage
• Adding plugins (2FA, organizations, passkeys, etc.)
• Troubleshooting auth issues on Heartwood or any Better Auth deployment
• Reviewing security posture before production deploy

Pair with:

heartwood-auth

spider-weave

turtle-harden

Grove Context: Heartwood

Heartwood is Grove's auth service, powered by Better Auth on Cloudflare Workers.

heartwood.grove.place

auth-api.grove.place

SESSION_KV

.grove.place

Everything in this skill applies directly to Heartwood. The

heartwood-auth

Quick Reference

Environment Variables

BETTER_AUTH_SECRET

openssl rand -base64 32

BETTER_AUTH_URL

https://auth-api.grove.place

BETTER_AUTH_TRUSTED_ORIGINS

Only define

baseURL

secret

File Location

CLI looks for

auth.ts

./

./lib

./utils

./src

--config

CLI Commands

npx @better-auth/cli@latest migrate    # Apply schema (built-in adapter)
npx @better-auth/cli@latest generate   # Generate schema for Prisma/Drizzle

Re-run after adding/changing plugins.

Core Configuration

appName

baseURL

BETTER_AUTH_URL

basePath

/api/auth

/

secret

BETTER_AUTH_SECRET

database

secondaryStorage

emailAndPassword

{ enabled: true }

socialProviders

{ google: { clientId, clientSecret }, ... }

plugins

trustedOrigins

Database

Direct connections: Pass

pg.Pool

mysql2

better-sqlite3

bun:sqlite

ORM adapters: Import from

better-auth/adapters/drizzle

better-auth/adapters/prisma

better-auth/adapters/mongodb

Critical gotcha: Better Auth uses adapter model names, NOT underlying table names. If Prisma model is

User

users

modelName: "user"

"users"

Rate Limiting

Better Auth has built-in rate limiting — enabled by default in production, disabled in development.

Why This Matters for Grove

Better Auth's rate limiter can replace custom threshold SDKs for auth endpoints. It's battle-tested, configurable per-endpoint, and integrates directly with the auth layer where it matters most.

Default Configuration

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  rateLimit: {
    enabled: true,       // Default: true in production
    window: 10,          // Time window in seconds (default: 10)
    max: 100,            // Max requests per window (default: 100)
  },
});

Storage Options

rateLimit: {
  storage: "secondary-storage", // Best for production
}

"memory"

"database"

"secondary-storage"

For Heartwood: Use

"secondary-storage"

Per-Endpoint Rules

Better Auth applies stricter defaults to sensitive endpoints:

• /sign-in

  ,

  /sign-up

  ,

  /change-password

  ,

  /change-email

  : 3 requests per 10 seconds

Override for specific paths:

rateLimit: {
  customRules: {
    "/api/auth/sign-in/email": {
      window: 60,  // 1 minute
      max: 5,      // 5 attempts
    },
    "/api/auth/sign-up/email": {
      window: 60,
      max: 3,      // Very strict for registration
    },
    "/api/auth/some-safe-endpoint": false, // Disable rate limiting
  },
}

Custom Storage

For non-standard backends:

rateLimit: {
  customStorage: {
    get: async (key) => {
      // Return { count: number, expiresAt: number } or null
    },
    set: async (key, data) => {
      // Store the rate limit data
    },
  },
}

Each plugin can optionally define its own rate-limit rules per endpoint.

Session Management

Storage Priority

1. If

   secondaryStorage

   defined → sessions go there (not DB)
2. Set

   session.storeSessionInDatabase: true

   to also persist to DB
3. No database +

   cookieCache

   → fully stateless mode

Key Options

session: {
  expiresIn: 60 * 60 * 24 * 7,   // 7 days (default)
  updateAge: 60 * 60 * 24,        // Refresh every 24 hours (default)
  freshAge: 60 * 60 * 24,         // 24 hours for sensitive actions (default)
}

freshAge

Cookie Cache Strategies

Cache session data in cookies to reduce DB/KV queries:

session: {
  cookieCache: {
    enabled: true,
    maxAge: 60 * 5,        // 5 minutes
    strategy: "compact",   // Options: "compact", "jwt", "jwe"
    version: 1,            // Change to invalidate all sessions
  },
}

compact

jwt

jwe

Gotcha: Custom session fields are NOT cached — they're always re-fetched from storage.

Security Configuration

Secret Management

Better Auth looks for secrets in order:

1. options.secret

   in config

2. BETTER_AUTH_SECRET

   env var

3. AUTH_SECRET

   env var

Requirements:

• Rejects default/placeholder secrets in production
• Warns if shorter than 32 characters
• Warns if entropy below 120 bits

CSRF Protection

Multi-layered by default:

1. Origin header validation —

   Origin

   /

   Referer

   must match trusted origins
2. Fetch metadata — Uses

   Sec-Fetch-Site

   ,

   Sec-Fetch-Mode

   ,

   Sec-Fetch-Dest

   headers
3. First-login protection — Validates origin even without cookies

advanced: {
  disableCSRFCheck: false,  // KEEP THIS FALSE
}

Trusted Origins

trustedOrigins: [
  "https://app.grove.place",
  "https://*.grove.place",          // Wildcard subdomain
  "exp://192.168.*.*:*/*",          // Custom schemes (Expo)
]

Dynamic computation:

trustedOrigins: async (request) => {
  const tenant = getTenantFromRequest(request);
  return [`https://${tenant}.grove.place`];
}

Validated parameters:

callbackURL

redirectTo

errorCallbackURL

newUserCallbackURL

origin

Cookie Security

Defaults are secure:

• secure: true

  when baseURL uses HTTPS or in production

• sameSite: "lax"

  (CSRF prevention while allowing navigation)

• httpOnly: true

  (no JavaScript access)

• __Secure-

  prefix when secure is enabled

advanced: {
  useSecureCookies: true,
  cookiePrefix: "better-auth",
  defaultCookieAttributes: {
    sameSite: "lax",
  },
  crossSubDomainCookies: {
    enabled: true,
    domain: ".grove.place",  // Note the leading dot
    additionalCookies: ["session_token", "session_data"],
  },
}

Warning: Cross-subdomain cookies expand attack surface. Only enable if you trust all subdomains.

IP-Based Security

advanced: {
  ipAddress: {
    ipAddressHeaders: ["x-forwarded-for", "x-real-ip"],
    ipv6Subnet: 64,            // Group IPv6 by /64
    disableIpTracking: false,  // Keep enabled for rate limiting
  },
  trustedProxyHeaders: true,   // Only if behind a trusted proxy
}

Background Tasks (Timing Attack Prevention)

Sensitive operations should complete in constant time. The

handler

waitUntil

Cloudflare Workers: Capture

ExecutionContext

// In your Worker fetch handler:
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // Create auth with ctx in scope
    const auth = createAuth(env, ctx);
    return auth.handler(request);
  },
};

// In your auth config factory:
function createAuth(env: Env, ctx: ExecutionContext) {
  return betterAuth({
    // ...
    advanced: {
      backgroundTasks: {
        handler: (promise) => ctx.waitUntil(promise),
      },
    },
  });
}

Vercel/Next.js: Use the

waitUntil

@vercel/functions

import { waitUntil } from "@vercel/functions";

advanced: {
  backgroundTasks: {
    handler: (promise) => waitUntil(promise),
  },
}

Ensures email sending doesn't leak information about whether a user exists.

Account Enumeration Prevention

Built-in protections:

1. Consistent response messages — Password reset always returns generic message
2. Dummy operations — When user isn't found, still performs token generation + DB lookups
3. Background email sending — Async to prevent timing differences

OAuth / Social Provider Security

PKCE (Automatic)

Better Auth automatically uses PKCE for all OAuth flows:

1. Generates 128-character random

   code_verifier

2. Creates

   code_challenge

   using S256 (SHA-256)
3. Validates code exchange with original verifier

State Parameter

account: {
  storeStateStrategy: "cookie",  // "cookie" (default) or "database"
}

State tokens: 32-character random strings, expire after 10 minutes, contain encrypted callback URLs + PKCE verifier.

Encrypt Stored OAuth Tokens

account: {
  encryptOAuthTokens: true,  // AES-256-GCM
}

Enable if you store OAuth tokens for API access on behalf of users.

Email & Password

Email Verification

emailVerification: {
  sendVerificationEmail: async ({ user, url }) => {
    await sendEmail({ to: user.email, subject: "Verify your email", url });
  },
  sendOnSignUp: true,
  requireEmailVerification: true,  // Blocks sign-in until verified
}

Password Reset

emailAndPassword: {
  sendResetPassword: async ({ user, url }) => {
    await sendEmail({ to: user.email, subject: "Reset your password", url });
  },
  password: {
    minLength: 8,   // Default
    maxLength: 128,  // Default
  },
  revokeSessionsOnPasswordReset: true,  // Log out all sessions
}

Security: Reset tokens are 24-character alphanumeric strings, expire after 1 hour, single-use.

Password Hashing

Default: scrypt. For Argon2id, provide custom

hash

verify

Two-Factor Authentication

Setup

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

// Server
plugins: [
  twoFactor({
    issuer: "Grove",  // Shown in authenticator apps
    totpOptions: { digits: 6, period: 30 },
    backupCodeOptions: { amount: 10, length: 10, storeBackupCodes: "encrypted" },
  }),
]

// Client
plugins: [
  twoFactorClient({
    onTwoFactorRedirect() {
      window.location.href = "/2fa";
    },
  }),
]

Run migrations after adding. The

twoFactorEnabled

Sign-In Flow with 2FA

1. User signs in with credentials
2. Response includes

   twoFactorRedirect: true

3. Session cookie removed temporarily
4. Two-factor cookie set (10-minute expiration)
5. User verifies via TOTP/OTP/backup code
6. Session cookie restored

Trusted Devices

Skip 2FA on subsequent sign-ins:

twoFactor({
  trustDeviceMaxAge: 30 * 24 * 60 * 60,  // 30 days
})

// During verification:
await authClient.twoFactor.verifyTotp({ code, trustDevice: true });

OTP (Email/SMS)

twoFactor({
  otpOptions: {
    sendOTP: async ({ user, otp }) => {
      await sendEmail({ to: user.email, subject: "Your code", text: `Code: ${otp}` });
    },
    period: 5,            // Minutes
    digits: 6,
    allowedAttempts: 5,
    storeOTP: "encrypted",
  },
})

Built-in 2FA Protections

• Rate limiting: 3 requests per 10 seconds on 2FA endpoints
• OTP attempt limiting: configurable max attempts
• Constant-time comparison prevents timing attacks
• TOTP secrets encrypted with symmetric encryption
• Backup codes encrypted by default
• Limitation: 2FA requires credential accounts — social-only accounts can't enable it

Organizations Plugin

Multi-tenant organization support:

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

plugins: [
  organization({
    // Limit who can create orgs
    allowUserToCreateOrganization: async (user) => {
      return user.emailVerified;
    },
  }),
]

Key Concepts

• Active organization stored in session — scopes API calls after

  setActive()

• Default roles: owner (full), admin (management), member (basic)
• Dynamic access control for custom runtime permissions
• Teams group members within organizations
• Invitations expire after 48 hours (configurable), email-specific
• Safety: Last owner cannot be removed or leave

Plugins Reference

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

twoFactor

organization

passkey

@better-auth/passkey

magicLink

emailOtp

username

phoneNumber

admin

apiKey

bearer

jwt

multiSession

sso

@better-auth/sso

oauthProvider

oidcProvider

openAPI

genericOAuth

Client plugins go in

createAuthClient({ plugins: [...] })

Always run migrations after adding plugins.

Client Setup

Import by framework:

better-auth/react

better-auth/svelte

better-auth/vue

better-auth/solid

better-auth/client

Key methods:

signUp.email()

signIn.email()

signIn.social()

signOut()

useSession()

getSession()

revokeSession()

revokeSessions()

Type Safety

// Infer types from server config
type Session = typeof auth.$Infer.Session;
type User = typeof auth.$Infer.Session.user;

// For separate client/server projects
createAuthClient<typeof auth>();

Hooks

Endpoint Hooks

hooks: {
  before: [
    {
      matcher: (ctx) => ctx.path === "/sign-in/email",
      handler: createAuthMiddleware(async (ctx) => {
        // Access: ctx.path, ctx.context.session, ctx.context.secret
        // Return modified context or void
      }),
    },
  ],
  after: [
    {
      matcher: (ctx) => true,
      handler: createAuthMiddleware(async (ctx) => {
        // Access: ctx.context.returned (response data)
      }),
    },
  ],
}

Database Hooks

databaseHooks: {
  user: {
    create: {
      before: async ({ data }) => { /* add defaults, return false to block */ },
      after: async ({ data }) => { /* audit log, send welcome email */ },
    },
  },
  session: {
    create: {
      after: async ({ data, ctx }) => {
        await auditLog("session.created", {
          userId: data.userId,
          ip: ctx?.request?.headers.get("x-forwarded-for"),
        });
      },
    },
  },
}

Hook context (

ctx.context

session

secret

authCookies

password.hash()

verify()

adapter

internalAdapter

generateId()

tables

baseURL

Common Gotchas

1. Model vs table name — Config uses ORM model name, not DB table name
2. Plugin schema — Re-run CLI after adding plugins (always!)
3. Secondary storage — Sessions go there by default, not DB
4. Cookie cache — Custom session fields NOT cached, always re-fetched
5. Stateless mode — No DB = session in cookie only, logout on cache expiry
6. Change email flow — Sends to current email first, then new email
7. 2FA + social — 2FA only works on credential accounts, not social-only
8. Last owner — Cannot be removed from or leave an organization
9. Rate limit memory — Memory storage resets on restart, bad for serverless

Production Security Checklist

• BETTER_AUTH_SECRET

  set (32+ chars, high entropy)

• BETTER_AUTH_URL

  uses HTTPS

• trustedOrigins

  configured for all valid origins
• Rate limiting enabled with appropriate per-endpoint limits
• Rate limit storage set to

  "secondary-storage"

  or

  "database"

  (not memory)
• CSRF protection enabled (

  disableCSRFCheck: false

  )
• Secure cookies enabled (automatic with HTTPS)

• account.encryptOAuthTokens: true

  if storing tokens
• Background tasks configured for serverless (capture

  ExecutionContext

  from fetch handler)
• Audit logging via

  databaseHooks

  or

  hooks

• IP tracking headers configured if behind proxy
• Email verification enabled
• Password reset implemented
• 2FA available for sensitive apps
• Session expiry and refresh intervals reviewed
• Cookie cache strategy chosen (

  jwe

  for sensitive session data)

• account.accountLinking

  reviewed

Complete Production Config Example

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

// Factory pattern — ctx comes from the Worker fetch handler
export function createAuth(env: Env, ctx: ExecutionContext) {
  return betterAuth({
    appName: "Grove",
    secret: env.BETTER_AUTH_SECRET,
    baseURL: "https://auth-api.grove.place",
    trustedOrigins: [
      "https://heartwood.grove.place",
      "https://*.grove.place",
    ],

    database: d1Adapter(env),
    secondaryStorage: kvAdapter(env),

    // Rate limiting (replaces custom threshold SDK for auth)
    rateLimit: {
      enabled: true,
      storage: "secondary-storage",
      customRules: {
        "/api/auth/sign-in/email": { window: 60, max: 5 },
        "/api/auth/sign-up/email": { window: 60, max: 3 },
        "/api/auth/change-password": { window: 60, max: 3 },
      },
    },

    // Sessions
    session: {
      expiresIn: 60 * 60 * 24 * 7,    // 7 days
      updateAge: 60 * 60 * 24,         // 24 hours
      freshAge: 60 * 60,               // 1 hour for sensitive actions
      cookieCache: {
        enabled: true,
        maxAge: 300,
        strategy: "jwe",
      },
    },

    // OAuth
    account: {
      encryptOAuthTokens: true,
      storeStateStrategy: "cookie",
    },

    // Security
    advanced: {
      useSecureCookies: true,
      crossSubDomainCookies: {
        enabled: true,
        domain: ".grove.place",
      },
      ipAddress: {
        ipAddressHeaders: ["x-forwarded-for"],
        ipv6Subnet: 64,
      },
      backgroundTasks: {
        handler: (promise) => ctx.waitUntil(promise),  // ctx captured from fetch handler
      },
    },

    // Plugins
    plugins: [
      twoFactor({
        issuer: "Grove",
        backupCodeOptions: { storeBackupCodes: "encrypted" },
      }),
      organization(),
    ],

    // Audit hooks
    databaseHooks: {
      session: {
        create: {
          after: async ({ data, ctx: hookCtx }) => {
            console.log(`[audit] session created: user=${data.userId}`);
          },
        },
      },
    },
  });
}

Resources

• Better Auth Docs
• Options Reference
• LLMs.txt
• GitHub
• Official Skills
• Init Options Source