= {\n user: {\n additionalFields: {\n // `input: false` keeps `role` server-only — clients cannot set it at\n // sign-up. Role is assigned by the first-user-admin hook; configure the\n // default self-sign-up role via `firstUserAdmin: { defaultRole }`.\n role: { type: 'string', defaultValue: 'user', input: false },\n },\n },\n emailAndPassword: { enabled: true },\n}\n```\n\n### 2. Users Collection\n\n```ts\n// src/collections/Users/index.ts\nimport type { CollectionConfig } from 'payload'\nimport { betterAuthStrategy } from '@delmaredigital/payload-better-auth'\n\nexport const Users: CollectionConfig = {\n slug: 'users',\n auth: {\n disableLocalStrategy: true,\n strategies: [betterAuthStrategy()],\n },\n access: {\n read: ({ req }) => {\n if (!req.user) return false\n if (req.user.role === 'admin') return true\n return { id: { equals: req.user.id } }\n },\n admin: ({ req }) => req.user?.role === 'admin',\n },\n fields: [\n { name: 'email', type: 'email', required: true, unique: true },\n { name: 'emailVerified', type: 'checkbox', defaultValue: false },\n { name: 'name', type: 'text' },\n { name: 'image', type: 'text' },\n {\n name: 'role',\n type: 'select',\n defaultValue: 'user',\n options: [\n { label: 'User', value: 'user' },\n { label: 'Admin', value: 'admin' },\n ],\n },\n ],\n}\n```\n\nEvery `additionalFields` entry needs a matching field here. Scalars map to the\nobvious Payload type; an array-typed one (`string[]` / `number[]`) needs a field\nthat stores an array — `json`, or `select` with `hasMany: true` — because the\nadapter writes real arrays, not serialized ones:\n\n```ts\n// better auth: roles: { type: 'string[]' }\n{ name: 'roles', type: 'json' }\n```\n\n> Upgrading from 0.11.x with the oauth-provider plugin or an array-typed\n> `additionalField`? Those columns hold JSON strings and need converting once —\n> see [Migrating stringified arrays](#migrating-stringified-arrays-0120).\n\n### 3. Payload Config\n\n```ts\n// src/payload.config.ts\nimport { buildConfig } from 'payload'\nimport { postgresAdapter } from '@payloadcms/db-postgres'\nimport { betterAuth } from 'better-auth'\nimport {\n betterAuthCollections,\n createBetterAuthPlugin,\n payloadAdapter,\n} from '@delmaredigital/payload-better-auth'\nimport { betterAuthOptions } from './lib/auth/config'\nimport { Users } from './collections/Users'\nimport { getBaseUrl } from './lib/auth/getBaseUrl'\n\nconst baseUrl = getBaseUrl()\n\nexport default buildConfig({\n collections: [Users],\n plugins: [\n betterAuthCollections({\n betterAuthOptions,\n skipCollections: ['user'],\n }),\n createBetterAuthPlugin({\n createAuth: (payload) =>\n betterAuth({\n ...betterAuthOptions,\n database: payloadAdapter({ payloadClient: payload }),\n advanced: { database: { generateId: 'serial' } },\n baseURL: baseUrl,\n secret: process.env.BETTER_AUTH_SECRET,\n trustedOrigins: [baseUrl],\n }),\n }),\n ],\n db: postgresAdapter({\n pool: { connectionString: process.env.DATABASE_URL },\n }),\n})\n```\n\n### 4. Client-Side Auth\n\n```ts\n// src/lib/auth/client.ts\n'use client'\n\nimport { createAuthClient, twoFactorClient } from '@delmaredigital/payload-better-auth/client'\nimport { passkeyClient } from '@better-auth/passkey/client'\n\nexport const authClient = createAuthClient({\n plugins: [twoFactorClient(), passkeyClient()],\n})\n\nexport const { useSession, signIn, signUp, signOut, twoFactor, passkey } = authClient\n```\n\n> Listing plugins inline (rather than using `createPayloadAuthClient()` or spreading `payloadAuthPlugins`) ensures `twoFactor` and other plugin methods are typed on the returned client.\n\n### 5. Server-Side Session\n\n```ts\nimport { headers } from 'next/headers'\nimport { getPayload } from 'payload'\nimport { getServerSession } from '@delmaredigital/payload-better-auth'\n\nexport default async function Dashboard() {\n const payload = await getPayload({ config })\n const headersList = await headers()\n const session = await getServerSession(payload, headersList)\n\n if (!session) { redirect('/login') }\n\n return Hello {session.user.name}
\n}\n```\n\nSessions slide the way Better Auth documents (`session.updateAge`): once the refresh window is reached, `getSession()` extends the session row and issues a refreshed cookie. `betterAuthStrategy` forwards that `Set-Cookie` on every Payload REST and GraphQL request, so the browser's cookie moves with the database. Where there is no response to carry a cookie — server components, `getServerSession()`, `payload.auth({ headers })` — the session is read without refreshing it, so the two can never drift apart. To let a Local API call refresh the session, tell Payload it may set headers and forward what it hands back:\n\n```ts\n// app/api/whoami/route.ts\nexport async function GET(req: Request) {\n const payload = await getPayload({ config })\n const { user, responseHeaders } = await payload.auth({ headers: req.headers, canSetHeaders: true })\n return Response.json({ user }, { headers: responseHeaders })\n}\n```\n\n**That's it!** The plugin automatically registers auth API endpoints at `/api/auth/*`, injects admin UI components, and handles session management.\n\n> **Using a non-default API route?** The plugin mounts Better Auth at `routes.api` + `authBasePath`, and Better Auth's own router 404s any request outside its `basePath` (default `/api/auth`). If your Payload config sets `routes: { api: '/api/payload' }`, tell Better Auth where it lives:\n>\n> ```ts\n> // inside createAuth\n> betterAuth({\n> basePath: '/api/payload/auth', // + \n> // ...\n> })\n> ```\n>\n> The plugin's admin components pick up `routes.api` automatically, and the plugin logs an error at startup (naming the exact value to set) if `basePath` doesn't match the mount.\n\n---\n\n## Atomic operations\n\nBetter Auth 1.7 requires every database adapter to implement two atomic primitives, and calls them on paths you are almost certainly using:\n\n| Primitive | Used by |\n| --- | --- |\n| `consumeOne` | Single-use credentials — email verification, password reset, magic links, email OTP, device-authorization codes |\n| `incrementOne` | Guarded counters — API-key quota and rate limits, two-factor backup codes, team member counts |\n\nPayload's Local API has no `DELETE … RETURNING` or `SET n = n + d`, so the adapter implements both as read-then-write and narrows the race window rather than eliminating it:\n\n- **`consumeOne`** reads the row, then deletes it by id. The row is returned **only if our own delete removed it** — if a concurrent caller got there first, Payload raises a 404 and we return `null`. That is what keeps a magic link or reset token single-use.\n- **`incrementOne`** reads the row, then writes with a guard that re-asserts both Better Auth's own precondition (e.g. `remaining > 0`) and the counter values the write was computed from. A racing writer's update matches no row, so the loser re-reads and retries (up to five times) instead of clobbering the winner.\n\n**The limit:** Payload resolves a `where` by finding rows and then mutating them, so a narrow window remains between its internal read and write. Under heavy concurrency on the *same row*, a quota decrement can be lost or a token consumed twice. This matches the guarantee Better Auth 1.6 provided for these flows, and is fine for typical traffic — but if you need strict cross-process guarantees for API-key quota, enforce it at the database with a `CHECK` constraint or a unique index rather than relying on the adapter alone.\n\n## Migrating stringified arrays (0.12.0)\n\nReleases up to 0.11.3 reported `supportsArrays: false` to Better Auth, so every\n`string[]` / `number[]` value was `JSON.stringify`'d on its way into Payload.\nThose columns hold `'[\"a\",\"b\"]'` where an array belongs. From 0.12.0 the adapter\nstores arrays natively, so those rows need converting once.\n\n**If you don't use the oauth-provider plugin and have no array-typed\n`additionalFields`, there is nothing to do** — nothing else in Better Auth uses an\narray field.\n\n**Use 0.12.1 or later.** On 0.12.0 this migration was a silent no-op on Postgres:\nit reported `converted: 0` against databases that were not clean. Payload writes\nthese fields to a `jsonb` column, so a stringified value is stored as a *jsonb\nstring*; on read node-postgres parses the jsonb and hands drizzle a JS string,\nand drizzle's `PgJsonb.mapFromDriverValue` parses it a second time. The stored\nstring becomes an array before Payload sees it, so a stringified row and a native\none are indistinguishable through `payload.find()`. 0.12.1 censuses the stored\nshape in SQL instead. If you ran the 0.12.0 migration, re-run it.\n\n### 1. Migrate\n\n```ts\nimport { migrateStringifiedArrays } from '@delmaredigital/payload-better-auth'\nimport { betterAuthOptions } from './lib/auth/config'\n\nconst results = await migrateStringifiedArrays({\n payload,\n betterAuthOptions,\n dryRun: true, // drop this once the report looks right\n})\nconsole.table(results)\n// [{ collection: 'oauthClients', field: 'redirectUris', scanned: 12,\n// converted: 12, skipped: 0, observedVia: 'stored-shape' }, …]\n```\n\nIt derives the fields to convert from your own Better Auth schema rather than a\nhardcoded list, so it covers whatever plugins you run, and it's safe to re-run —\nvalues already stored as arrays are left alone, and a string that doesn't parse to\nan array is skipped and counted rather than guessed at.\n\nRead `observedVia` alongside `converted`. On Postgres it must say `stored-shape`;\n`local-api` there would mean the count came from the laundered value and is not\ntrustworthy. If the stored shape can't be inspected at all, the migration throws\nrather than reporting a clean database.\n\n### 2. Verify against the database\n\n`converted: 0` is only good news if the census could see the stored shape. Confirm\nindependently:\n\n```sql\nSELECT jsonb_typeof(scopes) AS shape, count(*)\nFROM oauth_access_tokens GROUP BY 1;\n```\n\nYou want only `array` (and `null`). Any `string` rows are unconverted. To fix them\noutside the plugin:\n\n```sql\nUPDATE oauth_access_tokens\nSET scopes = (scopes #>> '{}')::jsonb\nWHERE jsonb_typeof(scopes) = 'string';\n```\n\n### 3. Only then, remove your own workarounds\n\nIf you were writing `JSON.stringify(uris)` into these columns, or parsing them back\nout on read, drop that — after migrating, the column holds one shape.\n\n**Do this last, and only after step 2 reads clean.** Removing a tolerant parse\nwhile unconverted rows remain is what turns this into an incident: raw SQL reads\ncarry no column type, so they bypass drizzle's mapper and still see the string.\nCode that reads `redirect_uris` via `drizzle.execute(sql`…`)` — a DCR connector\ngate, a consent screen — would get `[]` from an unconverted row. For a\nredirect-URI allowlist that's a hard lockout of a legitimate connector.\n\nThat raw-SQL path is also the real exposure of leaving rows unmigrated. Better\nAuth's own reads go through Payload, where the double-parse launders the value, so\n`/oauth2/authorize` keeps working — the damage is confined to code that queries\nthese columns directly.\n\n---\n\nFor MongoDB setup, API reference, customization, access control helpers, API key scopes, plugin compatibility, UI components (2FA, passkeys, password reset, passwordless login via magic-link & email-OTP), recipes, and types — see the **[full documentation](https://delmaredigital.github.io/payload-better-auth/)**.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}![\"Starter](\"https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white\"){kind=icon}
\n