Better Auth for Payload CMS

Installation

Requirements

Install

Optional plugins (install only what you use):

Environment Variables

bashCopy# Required
BETTER_AUTH_SECRET=your-secret-key-min-32-chars

# Optional — only needed if not using the getBaseUrl() helper
BETTER_AUTH_URL=http://localhost:3000

# OAuth Providers (if using social login)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

tsCopy// src/lib/auth/getBaseUrl.ts
export function getBaseUrl() {
  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`
  if (process.env.BETTER_AUTH_URL) return process.env.BETTER_AUTH_URL
  return 'http://localhost:3000'
}

Quick Start

tsCopy// src/lib/auth/config.ts
import type { BetterAuthOptions } from 'better-auth'

export const betterAuthOptions: Partial<BetterAuthOptions> = {
  user: {
    additionalFields: {
      // input: false keeps `role` server-only — clients cannot set it at sign-up.
      role: { type: 'string', defaultValue: 'user', input: false },
    },
  },
  session: {
    expiresIn: 60 * 60 * 24 * 30, // 30 days
  },
  emailAndPassword: { enabled: true },
}

tsCopy// src/collections/Users/index.ts
import type { CollectionConfig } from 'payload'
import { betterAuthStrategy } from '@delmaredigital/payload-better-auth'

export const Users: CollectionConfig = {
  slug: 'users',
  auth: {
    disableLocalStrategy: true,
    strategies: [betterAuthStrategy()],
  },
  access: {
    read: ({ req }) => {
      if (!req.user) return false
      if (req.user.role === 'admin') return true
      return { id: { equals: req.user.id } }
    },
    admin: ({ req }) => req.user?.role === 'admin',
  },
  fields: [
    { name: 'email', type: 'email', required: true, unique: true },
    { name: 'emailVerified', type: 'checkbox', defaultValue: false },
    { name: 'name', type: 'text' },
    { name: 'image', type: 'text' },
    {
      name: 'role',
      type: 'select',
      defaultValue: 'user',
      options: [
        { label: 'User', value: 'user' },
        { label: 'Admin', value: 'admin' },
      ],
    },
  ],
}

tsCopy// src/payload.config.ts
import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'
import { betterAuth } from 'better-auth'
import {
  betterAuthCollections,
  createBetterAuthPlugin,
  payloadAdapter,
} from '@delmaredigital/payload-better-auth'

export default buildConfig({
  collections: [Users],
  plugins: [
    betterAuthCollections({
      betterAuthOptions,
      skipCollections: ['user'],
    }),
    createBetterAuthPlugin({
      createAuth: (payload) =>
        betterAuth({
          ...betterAuthOptions,
          database: payloadAdapter({ payloadClient: payload }),
          advanced: { database: { generateId: 'serial' } },
          baseURL: baseUrl,
          secret: process.env.BETTER_AUTH_SECRET,
          trustedOrigins: [baseUrl],
        }),
    }),
  ],
  db: postgresAdapter({
    pool: { connectionString: process.env.DATABASE_URL },
  }),
})

tsCopy// src/lib/auth/client.ts
'use client'

import { createAuthClient, twoFactorClient } from '@delmaredigital/payload-better-auth/client'
import { passkeyClient } from '@better-auth/passkey/client'

export const authClient = createAuthClient({
  plugins: [twoFactorClient(), passkeyClient()],
})

export const { useSession, signIn, signUp, signOut, twoFactor, passkey } = authClient

tsCopyimport { createPayloadAuthClient } from '@delmaredigital/payload-better-auth/client'

export const authClient = createPayloadAuthClient()
export const { useSession, signIn, signUp, signOut, twoFactor } = authClient

tsCopyimport { createAuthClient, payloadAuthPlugins } from '@delmaredigital/payload-better-auth/client'
import { passkeyClient } from '@better-auth/passkey/client'
import { apiKeyClient } from '@better-auth/api-key/client'
import { stripeClient } from '@better-auth/stripe/client'

export const authClient = createAuthClient({
  plugins: [...payloadAuthPlugins, passkeyClient(), apiKeyClient(), stripeClient({ subscription: true })],
})

tsCopyimport { headers } from 'next/headers'
import { getPayload } from 'payload'
import { getServerSession } from '@delmaredigital/payload-better-auth'

export default async function Dashboard() {
  const payload = await getPayload({ config })
  const headersList = await headers()
  const session = await getServerSession(payload, headersList)

  if (!session) { redirect('/login') }

  return <div>Hello {session.user.name}</div>
}

MongoDB Setup

The adapter auto-detects MongoDB and configures itself accordingly. No special adapter configuration is needed.

Key Differences from Postgres

tsCopy// src/payload.config.ts
import { mongooseAdapter } from '@payloadcms/db-mongodb'

export default buildConfig({
  collections: [Users],
  plugins: [
    betterAuthCollections({ betterAuthOptions, skipCollections: ['user'] }),
    createBetterAuthPlugin({
      createAuth: (payload) =>
        betterAuth({
          ...betterAuthOptions,
          database: payloadAdapter({ payloadClient: payload }),
          // Do NOT set advanced.database.generateId
          secret: process.env.BETTER_AUTH_SECRET,
          trustedOrigins: ['http://localhost:3000'],
        }),
    }),
  ],
  db: mongooseAdapter({ url: process.env.DATABASE_URI! }),
})

tsCopy// Users collection
strategies: [betterAuthStrategy({ idType: 'text' })]

// Session helpers
export const { getServerSession, getServerUser } = createSessionHelpers<User>({
  idType: 'text',
})

API Reference

payloadAdapter(config)

Creates a Better Auth database adapter that uses Payload collections. Uses Better Auth's createAdapterFactory for schema-aware transformations.

tsCopypayloadAdapter({
  payloadClient: payload,
  adapterConfig: {
    enableDebugLogs: false,
    idType: 'number',
  },
})

tsCopybetterAuth({
  database: payloadAdapter({ payloadClient: payload }),
  user: { modelName: 'member' },        // 'users' → 'members'
  session: { modelName: 'auth_session' }, // 'sessions' → 'auth_sessions'
})

betterAuthCollections(options)

Payload plugin that auto-generates collections from Better Auth schema.

tsCopy// Customize roles
betterAuthCollections({
  betterAuthOptions,
  firstUserAdmin: {
    adminRole: 'super-admin',
    defaultRole: 'member',
    roleField: 'userRole',
  },
})

// Disable
betterAuthCollections({ betterAuthOptions, firstUserAdmin: false })

tsCopybetterAuthCollections({
  betterAuthOptions,
  customizeCollection: (modelKey, collection) => {
    if (modelKey === 'session') {
      return { ...collection, hooks: { afterDelete: [cleanupExpiredSessions] } }
    }
    return collection
  },
})

createBetterAuthPlugin(options)

Payload plugin that initializes Better Auth during Payload's onInit.

tsCopy// Permissions are auto-generated from collections
admin: {
  apiKey: {
    excludeCollections: ['internal-logs'],
    requiredRole: 'admin'
  }
}

betterAuthStrategy(options?)

Payload auth strategy for Better Auth session validation.

Session Helpers

getServerSession<TUser>(payload, headers)

Get the current session on the server with full type safety.

getServerUser<TUser>(payload, headers)

Shorthand for session.user.

createSessionHelpers<TUser>(options?)

Create typed session helpers. Define once, import everywhere — no generics at call sites.

tsCopy// lib/auth.ts
import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
import type { User } from '@/payload-types'

export const { getServerSession, getServerUser } = createSessionHelpers<User>()

// app/page.tsx — no generic needed
const session = await getServerSession(payload, headersList)

withBetterAuthDefaults(options)

Applies sensible defaults. Sets trustedOrigins: [baseURL] when not explicitly set.

API Key Configuration

API keys require the @better-auth/api-key package. Install it and configure directly in your Better Auth options:

bashCopypnpm add @better-auth/api-key

tsCopyimport { apiKey } from '@better-auth/api-key'

export const betterAuthOptions = {
  plugins: [
    apiKey(),
  ],
}

The plugin's API key management UI and permission enforcement utilities work automatically once the apiKey plugin is configured.

Customization

Role-Based Access Control

The login page checks for the admin role by default. Configure via admin.login.requiredRole.

tsCopyadmin: {
  login: {
    requiredRole: 'admin',                          // Single role
    requiredRole: ['admin', 'editor', 'moderator'], // Any of these
    requiredRole: null,                              // Disable checking
  },
}

Disabling Auto-Injection

tsCopycreateBetterAuthPlugin({
  createAuth,
  autoRegisterEndpoints: false,
  autoInjectAdminComponents: false,
})

tsCopyadmin: {
  loginViewComponent: '@/components/admin/CustomLogin',
  logoutButtonComponent: '@/components/admin/CustomLogout',
  disableBeforeLogin: true,
}

tsCopy// src/app/api/auth/[...all]/route.ts
import type { PayloadWithAuth } from '@delmaredigital/payload-better-auth'

export async function GET(request: NextRequest) {
  const payload = (await getPayload({ config })) as PayloadWithAuth
  return payload.betterAuth.handler(request)
}

export async function POST(request: NextRequest) {
  const payload = (await getPayload({ config })) as PayloadWithAuth
  return payload.betterAuth.handler(request)
}

Access Control Helpers

Pre-built access control functions for common authorization patterns.

tsCopyimport {
  isAdmin, isAdminField, isAdminOrSelf,
  hasRole, requireAllRoles,
  isAuthenticated, isAuthenticatedField,
  canUpdateOwnFields,
} from '@delmaredigital/payload-better-auth'

export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    read: isAuthenticated(),
    create: hasRole(['editor', 'admin']),
    update: hasRole(['editor', 'admin']),
    delete: requireAllRoles(['admin', 'content-manager']),
  },
  fields: [{
    name: 'internalNotes',
    type: 'textarea',
    access: { read: isAdminField() },
  }],
}

tsCopyaccess: {
  read: isAdminOrSelf({ adminRoles: ['admin'] }),
  update: canUpdateOwnFields({
    allowedFields: ['name', 'image', 'password'],
    userSlug: 'users',
    requireCurrentPassword: true,
  }),
  delete: isAdmin({ adminRoles: ['admin'] }),
}

tsCopyimport { normalizeRoles, hasAnyRole, hasAllRoles } from '@delmaredigital/payload-better-auth'

const roles = normalizeRoles(user.role)
hasAnyRole(user, ['admin', 'editor'])
hasAllRoles(user, ['admin', 'editor'])

API Key Permission Enforcement

Enforce API key permissions in your Payload access control using Better Auth's native permission system.

tsCopyimport { requirePermission, requireAllPermissions, allowSessionOrPermission } from '@delmaredigital/payload-better-auth'

access: {
  read: requirePermission('posts', 'read'),
  create: requirePermission('posts', 'write'),
  update: requirePermission('posts', 'write'),
  delete: requirePermission('posts', 'write'),
}

// Allow both session auth and API keys
read: allowSessionOrPermission('posts', 'read')

Two permission levels per collection: read (view only) and write (create, update, delete). Write implies read.

tsCopyimport { requireAnyPermission, requireAllPermissions, requireApiKey } from '@delmaredigital/payload-better-auth'

// Require ANY of these permissions
read: requireAnyPermission([
  { resource: 'posts', action: 'read' },
  { resource: 'pages', action: 'read' },
])

// Require ALL permissions
delete: requireAllPermissions([
  { resource: 'posts', action: 'write' },
  { resource: 'admin', action: 'write' },
])

// Just verify key is valid (no specific permissions)
read: requireApiKey()

Plugin Compatibility

The adapter uses Better Auth's createAdapterFactory which is schema-aware — it automatically supports all Better Auth plugins.

tsCopy// API Keys join
{ name: 'apiKeys', type: 'join', collection: 'apikeys', on: 'user' }

// Two-Factor join
{ name: 'twoFactor', type: 'join', collection: 'twoFactors', on: 'user' }

// Memberships join
{ name: 'memberships', type: 'join', collection: 'members', on: 'user' }

tsCopyuser: {
  deleteUser: {
    enabled: true,
    afterDelete: async (user) => {
      const collections = ['sessions', 'accounts', 'apikeys', 'passkeys', 'twoFactors']
      for (const col of collections) {
        try {
          await payload.delete({ collection: col, where: { user: { equals: user.id } } })
        } catch {} // Collection may not exist
      }
    },
  },
}

UI Components

User Registration

The LoginView automatically detects whether registration is available from your Better Auth configuration. If emailAndPassword.enabled: true (and not disableSignUp: true), the "Create account" link appears automatically.

Password Reset

The "Forgot password?" link appears automatically when the reset endpoint is available.

tsCopyimport { ForgotPasswordView, ResetPasswordView } from '@delmaredigital/payload-better-auth/components/auth'

<ForgotPasswordView
  logo={<MyLogo />}
  title="Forgot Password"
  loginPath="/admin/login"
/>

<ResetPasswordView
  logo={<MyLogo />}
  title="Reset Password"
  afterResetPath="/admin/login"
  minPasswordLength={8}
/>

Two-Factor Authentication

The LoginView handles 2FA inline automatically. When a user with 2FA enabled signs in, the form transitions to a second-factor step.

The step offers the factors that user actually has. Better Auth reports them on the sign-in response, so someone with no authenticator set up lands on the emailed code rather than a TOTP input they can't satisfy. "Use a backup code" is offered whenever the twoFactor plugin is active — the escape hatch for a lost authenticator — and "email me a code" when the plugin is configured with otpOptions.sendOTP, with resends on a 30-second cooldown. Both are detected server-side; admin.login.enableTwoFactorBackupCode and admin.login.enableTwoFactorEmailOtp are ceilings over that detection.

tsCopyimport { TwoFactorSetupView, TwoFactorVerifyView } from '@delmaredigital/payload-better-auth/components/twoFactor'

<TwoFactorSetupView logo={<MyLogo />} afterSetupPath="/admin" />
<TwoFactorVerifyView logo={<MyLogo />} afterVerifyPath="/admin" />

// As an admin view, prefer the server wrapper — it detects whether the
// account has a password and skips the confirmation step when it doesn't:
import { TwoFactorSetupViewWrapper } from '@delmaredigital/payload-better-auth/rsc'

tsCopyconst result = await signIn.email({ email, password })

if (result.data?.twoFactorRedirect) {
  // twoFactorMethods is the factors THIS user holds: ['totp'], ['otp'],
  // both, or [] when only backup codes are left. Offer from that list —
  // defaulting to TOTP strands anyone who never set up an authenticator.
  setTwoFactorMethods(result.data.twoFactorMethods)
  return
}

// Then verify with whichever factor they chose:
await twoFactor.verifyTotp({ code })        // authenticator app
await twoFactor.verifyBackupCode({ code })  // backup code
await twoFactor.sendOtp()                   // then verifyOtp({ code })

Passkeys

tsCopy// Enable in LoginView
admin: { login: { enablePasskey: true } }

// Or use standalone button
import { PasskeySignInButton } from '@delmaredigital/payload-better-auth/components/passkey'

<PasskeySignInButton
  onSuccess={(user) => router.push('/dashboard')}
  onError={(error) => setError(error)}
/>

tsCopy// Registration button
import { PasskeyRegisterButton } from '@delmaredigital/payload-better-auth/components/passkey'
<PasskeyRegisterButton passkeyName="My MacBook" onSuccess={refetch} />

// Full management UI
import { PasskeysManagementClient } from '@delmaredigital/payload-better-auth/components/passkey'
<PasskeysManagementClient title="Manage Passkeys" />

// Or use the auth client directly (requires passkeyClient() in your client plugins)
await authClient.passkey.addPasskey({ name: 'My Device' })
await authClient.passkey.listUserPasskeys()
await authClient.passkey.deletePasskey({ id: passkeyId })

Passwordless Sign-In (Magic Link & Email OTP)

The LoginView auto-detects the Better Auth magicLink() and emailOTP() plugins and surfaces "Email me a link" / "Email me a code" options on the admin login. If your Better Auth config sets emailAndPassword.enabled: false, the password field is hidden automatically and a passwordless method becomes the primary action.

tsCopy// Each option defaults to 'auto' (show iff the matching plugin is installed).
// Force on/off or hide the password field for passwordless-only sign-in:
admin: {
  login: {
    enableMagicLink: 'auto',   // requires magicLink() plugin
    enableEmailOtp: 'auto',    // requires emailOTP() plugin
    enablePassword: false,     // hide password field (passwordless-only)
    magicLinkCallbackURL: '/admin',
    enableSocial: ['google', 'github'], // opt-in; socialProviders or genericOAuth ids
  },
}

Server-side wiring stays yours: configure the magicLink() / emailOTP() plugins and their email senders in your Better Auth instance, and the UI lights up automatically. Added in v0.7.5.

Social Sign-In

Set admin.login.enableSocial to true (every resolved provider) or an array of provider ids to surface "Continue with …" buttons on the admin login page. Configure socialProviders in your Better Auth instance as usual — the UI reflects what Better Auth actually resolved, so a provider you switched off with enabled: false never gets a button that would fail on click.

Generic OAuth / OIDC (SSO) providers work too. Since Better Auth 1.7, genericOAuth() registers its providers as first-class social providers, so a Keycloak, Zitadel, Okta, Auth0 or Entra ID provider appears alongside the built-in ones with no custom login view. Allowlist it by its providerId, and give it a name to control the button label — { providerId: 'zitadel', name: 'Company SSO' } renders as "Continue with Company SSO". Fixed in v0.11.3 — before that, generic providers were filtered out.

plugins: [
  genericOAuth({
    config: [
      keycloak({ clientId, clientSecret, issuer: process.env.KEYCLOAK_ISSUER }),
      { providerId: 'zitadel', name: 'Company SSO', clientId, clientSecret, discoveryUrl },
    ],
  }),
],
// admin.login
enableSocial: ['github', 'keycloak', 'zitadel'],

Security Management UI

Auto-injected management views based on enabled plugins:

Recipes

tsCopy// src/lib/auth/instance.ts
let authInstance: AuthInstance | null = null

export function setAuthInstance(auth: AuthInstance) { authInstance = auth }
export function getAuthInstance() {
  if (!authInstance) throw new Error('Auth not initialized')
  return authInstance
}

tsCopycreateBetterAuthPlugin({
  createAuth: (payload) => {
    const auth = betterAuth({ ...betterAuthOptions, database: payloadAdapter({ payloadClient: payload }) })
    setAuthInstance(auth)
    return auth
  },
})

tsCopydatabaseHooks: {
  user: {
    update: {
      after: async (user, ctx) => {
        if (!user.emailVerified) return
        const existing = await ctx?.context?.adapter?.findOne({
          model: 'member', where: [{ field: 'userId', value: user.id }],
        })
        if (existing) return

        const auth = getAuthInstance()
        await auth.api.createOrganization({
          body: { name: `${user.name}'s Workspace`, slug: generateSlug(user.name), userId: user.id },
        })
      },
    },
  },
}

Types

tsCopyimport type {
  PayloadWithAuth,
  PayloadRequestWithBetterAuth,
  BetterAuthReturn,
  CollectionHookWithBetterAuth,
  EndpointWithBetterAuth,
} from '@delmaredigital/payload-better-auth'

// Generated schema types
import type {
  User, BetterAuthSession, Account,
  Apikey, Passkey, Organization, Member, TwoFactor,
} from '@delmaredigital/payload-better-auth'

Regenerate types after adding plugins: