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
scopes	—	Custom scope definitions
includeCollectionScopes	auto	Include auto-generated collection scopes
excludeCollections	auth collections	Collections to exclude from scopes
defaultScopes	[]	Default pre-selected scopes
requiredRole	'admin'	Role required to manage API keys

tsCopy// Custom scopes
admin: {
  apiKey: {
    scopes: {
      'content:read': {
        label: 'Read Content',
        description: 'View posts and pages',
        permissions: { posts: ['read'], pages: ['read'] }
      },
    },
    defaultScopes: ['content:read']
  }
}

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 { validateApiKey, hasScope } from '@delmaredigital/payload-better-auth'

const keyInfo = await validateApiKey(req)
if (!keyInfo) return Response.json({ error: 'Invalid' }, { status: 401 })
if (!hasScope(keyInfo.scopes, 'custom:action')) { /* 403 */ }

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