Better Auth for Payload CMS

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',
})

1. Remove generateId: 'serial' from your Better Auth config
2. Change betterAuthStrategy() to use idType: 'text'
3. Update createSessionHelpers to idType: 'text'
4. Remove explicit idType: 'number' from adapterConfig
5. Switch Payload's database adapter to mongooseAdapter
6. Remove idFieldsAllowlist/idFieldsBlocklist if set

By default, the adapter uses standard collection names. Only use modelName to customize:

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

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
  },
})

Option	Default	Description
admin.disableLogoutButton	false	Disable logout button injection
admin.disableBeforeLogin	false	Disable BeforeLogin redirect
admin.disableLoginView	false	Disable login view injection
admin.login.title	'Login'	Custom login page title
admin.login.afterLoginPath	'/admin'	Redirect path after login
admin.login.requiredRole	'admin'	Required role(s) for admin. null to disable.
admin.login.requireAllRoles	false	Require ALL roles instead of any
admin.login.enablePasskey	false	Enable passkey sign-in. 'auto' to detect.
admin.login.enableSignUp	'auto'	Enable registration
admin.login.defaultSignUpRole	'user'	Default role for new users
admin.login.enableForgotPassword	'auto'	Enable forgot password
admin.login.resetPasswordUrl	—	Custom password reset URL
admin.enableManagementUI	true	Enable security management views

Option	Default	Description
excludeCollections	auth collections	Collections to exclude from permissions UI
requiredRole	'admin'	Role required to manage API keys

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

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)
}

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'])

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()

Payload uses join fields to establish queryable parent-to-child relationships. When a plugin creates a model with a foreign key, add a join field to the parent collection:

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
      }
    },
  },
}

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}
/>

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

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

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

if (result.data?.twoFactorRedirect) {
  // Show TOTP verification form
  setTwoFactorRequired(true)
  return
}

// Then verify with:
await twoFactor.verifyTotp({ code: totpCode })

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 })

Use a lazy auth instance singleton to call auth.api.createOrganization() from database hooks (so organizationHooks fire properly).

1. Create an auth instance singleton

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
}

2. Store after creation

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

3. Use in database hooks

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 },
        })
      },
    },
  },
}