better-auth

better-auth

Features

• Added Cloudflare as a built-in social provider with client-secret and PKCE support.

• Enabled schema validation during initialization by default, including in production, and rejected authentication requests on detected mismatches.

• Added isPasswordCompromised for checking passwords against Have I Been Pwned in custom server-side flows.

Bug Fixes

• Aligned generated OpenAPI required fields with runtime validation.

• Handled malformed custom-scheme callback URLs without excessive processing.

• Improved Auth0 domain normalization to avoid slow trailing-slash processing.

• Prevented generic OAuth discovery failures from taking down the authentication API.

• Tracked email OTP sign-ins in the last login method plugin.

• Fixed callback hooks being skipped after proxied OAuth sign-ins and preserved server state when callback cookies are unavailable. The legacy /oauth-proxy-callback endpoint is deprecated and will be removed in the next minor release.

• Fixed getSession failures when cookie caching is disabled and cached session cookies remain.

• Fixed TOTP re-enrollment replacing an active authenticator and its backup codes.

• Prevented duplicate session requests and hydration mismatches in Nuxt useFetch.

• Improved dynamic organization role permission check performance.

• Added type-safe Nuxt useFetch integration for the Vue client's useSession hook.

• Restored compatibility with 1.6 account schemas by identifying accounts with (providerId, accountId) instead of issuer.

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed permanent user bans to clear expiration dates from previous temporary bans.

• Fixed client types with more plugins being assignable to types declaring fewer plugins.

• Added warnings for invalid signed session data in the cookie cache.

• Fixed disabled MyISAM indexes from satisfying migration index checks.

• Fixed programmatic migrations on Cloudflare D1 while preserving existing-index validation.

• Allowed ~ in relative callback URLs validated by trusted-origin checks.

• Improved validation of relative callback and redirect URLs with paths, queries, and fragments.

• Allowed same-origin form submissions with Referrer-Policy: no-referrer while continuing to reject untrusted origins.

• Improved getTestInstance performance with a faster default password hasher.

• Standardized built-in placeholder emails to the namespaced {identifier}@{namespace}.placeholder.invalid format.

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Added native database transaction support to test instances for PostgreSQL and MySQL.

• Updated bundled dependencies (jose, nanostores, noble crypto packages, SimpleWebAuthn) to their latest compatible releases, with no changes required to existing projects.

For detailed changes, see CHANGELOG

better-auth

Breaking Changes

• breaking

  Moved database joins out of experimental into the stable advanced.database.joins option

  Migration: Replace experimental: { joins: true } with advanced: { database: { joins: true } }. Drizzle and Prisma users should regenerate their schema (npx auth@latest generate) so it includes the required relations.

• breaking

  Scoped account identity by trusted issuer, keying accounts on (issuer, accountId)

  Migration: Accounts now require Account.issuer. Read provider identity from accountInfo.account.accountId, drop mapping.id from SSO configs, and give the microsoftEntraId helper a concrete tenant GUID. Apply the account-identity backfill in the 1.7 upgrade guide before deploying.

• breaking

  Required captcha endpoint entries to match full auth paths, with wildcard support

  Migration: Replace partial paths such as /sign-in with explicit wildcards like /sign-in/* or /sign-in/**.

• breaking

  Moved the MCP plugin into its own @better-auth/mcp package built on the OAuth provider

  Migration: Install @better-auth/mcp and @better-auth/cimd, add the now-required jwt() plugin, and move options nested under oidcConfig to flat mcp({ ... }) options. Rename withMcpAuth to requireMcpAuth and mcpHandler to createMcpProtectedRequestHandler. Regenerate the schema (npx auth migrate): oauthApplication becomes oauthClient, plus new oauthRefreshToken and oauthClientAssertion tables.

• breaking

  Added OIDC back-channel logout so ending a session cuts off every connected app's API access

  Migration: Introspecting an access token whose session has ended now returns { active: false }, and /oauth2/userinfo rejects it. Clients opt into notifications by registering backchannel_logout_uri. Run the schema migration for the new oauthClient and oauthAccessToken columns.

• breaking

  Modeled OAuth protected resources explicitly, with per-resource TTLs, scopes, claims, and signing pins

  Migration: validAudiences is removed: move each resource identifier into resources and link restricted clients through oauthClientResource. @better-auth/mcp now requires an explicit resource. Run npx @better-auth/cli generate and apply the migration before deploying.

• breaking

  Decoupled SCIM provisioning from the organization plugin

  Migration: SCIM configuration, client APIs, database schema, and the Group model are all replaced, and provisioning state cannot migrate in place. Follow the SCIM cutover in the 1.7 upgrade guide, including a full directory reprovision, before resuming traffic.

• breaking

  Added OTP-only two-factor enablement with a discriminated enableTwoFactor response

  Migration: enableTwoFactor now returns a method field ("otp" or "totp"); narrow on it before reading totpURI and backupCodes. Pass method: "otp" for OTP enrollment, which requires otpOptions.sendOTP.

• breaking

  Resolved the auth origin from Host by default when using a dynamic baseURL

  Migration: If your proxy exposes the public hostname only through x-forwarded-host, set advanced.trustedProxyHeaders: true. Deployments where the proxy rewrites Host (nginx default, Vercel, Cloudflare, Netlify) are unaffected.

• breaking

  Added unique lookup indexes for the device authorization deviceCode and userCode columns

  Migration: Resolve duplicate code values before applying the migration. MySQL and SQL Server installations must also convert both columns to bounded strings and clean up values longer than 191 characters.

• breaking

  Enforced S256 PKCE in the Electron sign-in flow and hardened custom-scheme origin checks

  Migration: Upgrade the @better-auth/electron client and server together and add your app's scheme to trustedOrigins. The code_challenge_method parameter and disableOriginOverride option are removed, and host-bearing custom-scheme entries now match that host exactly.

• breaking

  Identified Microsoft Entra accounts by the stable oid claim

  Migration: Migrate existing Microsoft account rows created from sub before upgrading. Tokens without a valid oid are rejected.

• breaking

  Required a Google client ID before Google One Tap verifies ID tokens

  Migration: Configure oneTap({ clientId }) or socialProviders.google.clientId.

• breaking

  Removed the deprecated oidcProvider plugin

  Migration: Move OIDC authorization-server integrations to @better-auth/oauth-provider.

• breaking

  Rewrote the generic OAuth plugin as a first-class social provider with OAuth 2.1 defaults

  Migration: Replace signIn.oauth2({ providerId }) with signIn.social({ provider }), oauth2.link() with linkSocial(), and drop genericOAuthClient(). Callbacks move to /api/auth/callback/:id, pkce now defaults to true, and issuer and requireIssuerValidation are removed in favor of OIDC discovery.

• breaking

  Separated OAuth device grant ownership into oauthDeviceAuthorization()

  Migration: The OAuth integration replaces the optional resource column with oauthClientId and resources, so regenerate and apply the schema. Let pending device codes expire before upgrading from an earlier 1.7 prerelease.

• breaking

  Verified provider id_tokens with a single shared verifier

  Migration: Custom UpstreamProvider implementations replace the removed verifyIdToken method with an idToken config carrying a JWKS source, issuer, and audience. PayPal client id_token sign-in now returns ID_TOKEN_NOT_SUPPORTED; its redirect flow is unchanged.

Features

• Added clientAssertion support to the Microsoft Entra ID social provider

• Made the Auth instance directly fetchable

• Added per-provider requireEmailVerification for social sign-in

• Added a user.validateUserInfo gate for rejecting an identity before a user is created or linked

• Added hydrateSession so useSession returns server-fetched data on the first render

• Added compound table indexes to plugin database schemas

• Added allowIdpInitiated support for IdP-initiated flows through a secure server-side bounce

• Added RP-initiated logout so signOut() can also sign users out of the OpenID provider

• Added refreshTokenParams for forwarding extra parameters on generic OAuth token refresh

• Verified discovery id_tokens against the provider JWKS and enabled id_token sign-in for generic OAuth

better-auth

Bug Fixes

• Fixed concurrent cold-start requests from intermittently losing authentication or transaction context due to an async storage initialization race

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Improved deleteSessions performance by running deletes in parallel instead of sequentially

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Prevented duplicate session requests during React Suspense retries while preserving revalidation for interrupted refreshes

• Restored client plugin declaration compatibility for downstream TypeScript consumers

For detailed changes, see the CHANGELOG.

better-auth

Bug Fixes

• Fixed duplicate session requests being made across Suspense retries

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed session cleanup on user deletion to also remove sessions from secondary storage

• Fixed findSessions to skip invalid secondary-storage session entries without discarding other valid sessions

• Fixed email OTP sign-up to pass the verification type to custom OTP generators

• Fixed email OTP password reset to allow retrying after entering an invalid password

• Fixed email OTP verification to no longer reveal whether an email is registered before the OTP is verified

• Fixed jwtClient() collapsing createAuthClient type inference when combined with other client plugins

• Fixed JWT key minting inside database transactions to use the transaction-scoped adapter, preventing deadlocks on SQLite and ensuring keys commit with their surrounding transaction on Postgres and MySQL

• Fixed oAuthProxy to preserve Apple user data from form_post callbacks

• Fixed oneTapClient() collapsing createAuthClient type inference when combined with other client plugins

• Fixed database rate-limit cleanup to complete when no background task handler is configured

• Improved nextCookies performance in instrumented Next.js applications by reusing the next/headers import promise

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed Apple OAuth not sending the PKCE code challenge during authorization, causing token exchange failures

• Fixed Google One Tap creating new users when sign-up was disabled on the Google provider

• Fixed $fetch and $store not being exposed on the Solid client

• Fixed internal adapter queries being routed to the wrong table when a built-in table's modelName was set to another table's schema key (e.g. user.modelName = "account").

For detailed changes, see CHANGELOG

better-auth

Features

• Added request context (ctx) as a third argument to verifyIdToken, enabling custom ID token verifiers to read request headers

• Added beforeStoreCookie option to the last-login-method plugin for GDPR compliance

Bug Fixes

• Replaced flaky MongoDB where-coercion integration test with a direct unit test for more reliable test runs

• Fixed the get-session endpoint to include no-store cache control headers, preventing stale session data from being served

• Fixed SQLite migration diffs to recognize BIGINT as a valid number type, preventing spurious pending changes on rate limiter columns

• Fixed auth requests failing when request cloning throws an error inside verification callbacks

• Fixed useSession({ throw: true }) incorrectly excluding null from its data type

• Fixed auth query revalidation and signal listeners not being restored after a client component remounts

• Fixed the CookieAttributes index signature type to be more precise

• Fixed silent misrouting of adapter queries when user.modelName was set to a value that collides with another schema key

• Fixed Kysely migration generation producing duplicate indexes for fields marked both unique and index

• Fixed magic-link and email-OTP send endpoints to validate the Origin header on cookieless requests, preventing cross-origin abuse

• Fixed remote MCP auth 401 challenge headers being hidden from browser clients due to missing CORS exposure

• Fixed OpenAPI schema to include plugin user fields (such as username and displayUsername) in /sign-up/email and /update-user request bodies

• Fixed organization.listMembers failing with "User not found for member" for organizations with more than ~100 members

• Fixed organization invitations to use database-generated IDs when advanced.database.generateId is configured, matching the behavior of other models

• Fixed getDefaultModelName to prefer exact schema key matches over modelName aliases, preventing adapter queries from being misrouted when a built-in table's name collides with another schema key

For detailed changes, see CHANGELOG