@better-auth/test-utils

[!IMPORTANT]
Action required

• If you use ID token sign-in with a provider that has no clientId, set clientId to every client ID your apps sign in with.

better-auth

Bug Fixes

• Fixed the JWT plugin to verify JWTs and session cookie-cache JWTs with the stored key's algorithm instead of the token header's, and to warn when signing or verifying a JWT without an issuer or audience

• Fixed OAuth callbacks completed through the OAuth proxy to run the same checks as the standard OAuth callback, including issuer and ID token nonce validation

• Fixed auth.api.getSession() to keep the original database error as error.cause when the session lookup fails

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Fixed mapProfileToUser failing to typecheck under exactOptionalPropertyTypes when it returns undefined for name, email, or image

• Fixed ID token sign-in to reject tokens when the provider has no client ID, since their audience cannot be checked

• Fixed a custom Facebook getUserInfo to no longer receive client-submitted access tokens issued to another Facebook app, and ID tokens missing exp or iat are now rejected

• Restored the Twitch and Paybin ID token handling from before 1.7.11, which made account info fail once the ID token stored at sign-in expired

• Added a cause option as a third argument to APIError.from() to keep the underlying error for server-side callers without exposing it in the response

For detailed changes, see CHANGELOG

@better-auth/mcp

Bug Fixes

• Fixed requireMcpAuth to accept only OAuth access tokens and reject session JWTs from the JWT plugin, even when they share the issuer and audience

For detailed changes, see CHANGELOG

@better-auth/sso

Bug Fixes

• Fixed OIDC SSO sign-in to reject ID tokens missing exp or iat and providers with an empty client ID, matching social sign-in

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed repeated PostgreSQL migration diffs for int8 columns.

• Fixed database-backed rate limiting returning an excessively large X-Retry-After value.

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Fixed plugin init returns with options: undefined failing type checks under exactOptionalPropertyTypes.

• Fixed ID token signature and claim validation for Twitch and Paybin sign-in. Custom Paybin issuers must publish RS256 signing keys at <issuer>/.well-known/jwks.json.

• Reduced installation size while preserving OpenTelemetry instrumentation attributes.

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Bug Fixes

• Fixed OpenAPI schemas for /oauth2/consent and /oauth2/continue to match their redirect responses.

• Fixed CIMD metadata refreshes overwriting concurrent administrator changes to discovered clients.

For detailed changes, see CHANGELOG

@better-auth/expo

Bug Fixes

• Fixed Expo social account linking with ID tokens when a session cookie is present.

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed Captcha and OpenAPI plugin subpath imports and type resolution for better-auth/plugins/multi-session and better-auth/test.

• Fixed Google One Tap sign-ins not recording google as the last login method.

• Fixed imports from better-auth/plugins/one-tap failing with a not-exported error.

• Fixed Google One Tap ignoring plugin-level autoSelect and cancelOnTapOutside settings.

• Fixed Google One Tap sign-ins ignoring configured Google profile mapping and user info updates.

• Fixed Google One Tap calling a prompt method unsupported by FedCM and retrying skipped prompts.

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Features

• Added optional self-service signing key rotation for private_key_jwt clients.

Bug Fixes

• Fixed valid DPoP proofs being rejected for parameterized routes and URLs with trailing slashes.

• Fixed native clients with HTTP loopback callbacks being rejected when application type inference is enabled.

• Fixed device-code clients being unable to refresh access for approved resources omitted from a token poll.

• Fixed OAuth consent without a reference overwriting or reusing consent for a different reference.

• Fixed dynamic client registration rejecting requests that include both supported and unsupported grants.

• Fixed attempts to change cached trusted clients returning HTTP 500 instead of HTTP 400.

• Improved errors for unknown OAuth client_id values to say client not found.

• Fixed PKCE verifier errors to return the specified HTTP 400 response and error code.

• Fixed unknown OAuth clients receiving invalid_grant instead of invalid_client at the token endpoint.

• Fixed unverifiable JWT access tokens causing server errors at /oauth2/userinfo, /oauth2/introspect, and /oauth2/revoke.

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Limited JWKS refetches for unknown key IDs to protect servers from repeated requests.

• Fixed unreachable JWKS endpoints being reported as invalid tokens instead of server errors.

For detailed changes, see CHANGELOG

@better-auth/mongo-adapter

Bug Fixes

• Fixed MongoDB findMany ignoring ID sorting and potentially repeating or skipping paginated results.

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Fixed onAPIError.onError handlers to finish before responses are sent and log failures without interrupting requests

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Bug Fixes

• Added isContinuation to postLogin.shouldRedirect so users can complete authorization after selecting an organization

• Fixed DPoP validation for token and UserInfo requests behind proxies that rewrite request URLs

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Aligned cookie security attributes with RFC 6265bis

• Added SvelteKit 3 to the supported peer dependency range

• Fixed stale cookies persisting after customSession sessions expire or are revoked

• Fixed customSession treating session lookup errors as signed-out users

• Fixed sign-in failures, replay checks, and SIWE email handling with generateId: "uuid"

• Removed non-returned custom fields from inferred output schema types

• Fixed Kysely migration foreign keys when custom table names match another model key

• Reduced organization plugin server bundles by excluding unused Zod locales

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed generic OAuth providers remaining unavailable after discovery fails at startup by retrying on subsequent requests

• Fixed lastLoginMethod sign-in failures when cookieName or maxAge is explicitly undefined

• Fixed magic link verification changing percent-encoded characters in callback URLs

• Fixed type errors when using oauthProvider() or mcp() with exactOptionalPropertyTypes

• Fixed organization plugin type errors in projects with skipLibCheck: false

• Fixed failed password resets consuming reset links or OTPs before the new password is saved

• Fixed password resets and changes retaining the new password when database session revocation fails

• Fixed phone number password resets to use a configured verifyOTP callback

• Fixed secondary-storage session failures leaving sign-ups, passkey registrations, or SSO sign-ins in an inconsistent state

• Fixed missing device sessions and failed automatic session switching after cache eviction

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Fixed ID token sign-in failures caused by up to 30 seconds of clock difference with identity providers

• Fixed Atlassian user info errors being mislabeled as Figma errors in logs

• Fixed authentication requests hanging after interrupted async context initialization

• Fixed recognition of valid AsyncLocalStorage initialized after importing Better Auth but before first use, and corrected misleading errors for invalid runtime-provided values in edge and browser fallbacks.

• Fixed after hooks being skipped for writes retained after a failed request on adapters without transactions

• Fixed Microsoft Entra ID sign-in and account linking with ID tokens when signing keys omit alg

• Fixed sign-in failures, replay checks, and SIWE email handling with generateId: "uuid"

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed concurrent MongoDB writes failing with transaction conflicts by retrying transient errors

• Added support for host-bearing custom-scheme redirect URIs for native OAuth clients

• Fixed password resets and changes retaining the new password when database session revocation fails

• Fixed secondary-storage session failures leaving sign-ups, passkey registrations, or SSO sign-ins in an inconsistent state

• Fixed missing device sessions and failed automatic session switching after cache eviction

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Features

• Added support for pausing and resuming OAuth clients through adminUpdateOAuthClient

• Added support for linking protected resources when registering a client with adminCreateOAuthClient

• Added resource identifier validation for adminCreateOAuthResource and configured resources

• Added clientId to clientPrivileges checks for actions on existing OAuth clients

Bug Fixes

• Fixed sign-in failures, replay checks, and SIWE email handling with generateId: "uuid"

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Added support for host-bearing custom-scheme redirect URIs for native OAuth clients

• Fixed startup resource-seeding failures from blocking authentication routes until restart

• Fixed type errors when using oauthProvider() or mcp() with exactOptionalPropertyTypes

For detailed changes, see CHANGELOG

@better-auth/sso

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed SSO provider registration and updates rejecting partial mapping values that omit defaulted fields

• Fixed SAML providers with linked accounts rejecting IdP signing certificate rotation

• Rejected OIDC SSO providers whose configured issuer does not match discovery, preventing later sign-in failures

• Fixed SAML providers with linked accounts rejecting changes to their post-login callbackUrl

• Fixed OIDC sign-in when the mapped email claim contains a list of addresses

For detailed changes, see CHANGELOG

@better-auth/scim

Bug Fixes

• Fixed SCIM reprovisioning of inactive users with an existing externalId

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed SCIM requests silently ignoring attribute names with different letter case

• Fixed concurrent SCIM updates to return 409 instead of 500 when a unique value is already claimed

• Fixed SCIM User and Group requests rejecting nullable attributes sent as JSON null

For detailed changes, see CHANGELOG

@better-auth/mongo-adapter

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed failed MongoDB transaction commits leaving transactions open and blocking other writes

• Fixed concurrent MongoDB writes failing with transaction conflicts by retrying transient errors

• Fixed MongoDB authentication errors masking the original transaction commit failure

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed Drizzle sign-in, session refresh, and date filtering with string-based date columns

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

• Fixed cross-request I/O errors from concurrent D1 queries on a shared auth instance with Kysely 0.29

For detailed changes, see CHANGELOG

@better-auth/mcp

Bug Fixes

• Fixed @better-auth/mcp type errors with exactOptionalPropertyTypes and skipLibCheck: false

• Fixed type errors when using oauthProvider() or mcp() with exactOptionalPropertyTypes

For detailed changes, see CHANGELOG

@better-auth/api-key

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

@better-auth/cimd

Bug Fixes

• Added support for host-bearing custom-scheme redirect URIs for native OAuth clients

For detailed changes, see CHANGELOG

@better-auth/electron

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

@better-auth/memory-adapter

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

@better-auth/passkey

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

@better-auth/prisma-adapter

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

@better-auth/stripe

Bug Fixes

• Stopped reporting completed one-time Stripe checkouts as webhook failures

For detailed changes, see CHANGELOG

@better-auth/telemetry

Bug Fixes

• Aligned @better-auth/utils and better-call dependency versions across official packages

For detailed changes, see CHANGELOG

better-auth

Magic Link upgrade: Upgrade servers sharing verification storage together, request new Magic Links, and restart pending OAuth/SAML sign-ins. No database migration is required. See the critical advisory for affected configurations and custom storage changes.

Bug Fixes

• security

  Fixed a critical Magic Link account-takeover vulnerability.

• Fixed ID-token sign-in ignoring the social provider’s disableSignUp setting.

• Fixed OAuth Proxy accepting sign-in state as a provider profile.
  Upgrade all OAuth Proxy participants together; see the OAuth Proxy upgrade guidance.

• Fixed CAPTCHA errors missing the JSON Content-Type header.

• Fixed the active organization failing to refresh after sign-in when a session hook selects the initial organization.

• Fixed rate-limit errors missing the JSON Content-Type header.

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Features

• Added optional validateRedirectUri validation for trusted deployments with dynamic OAuth redirect URIs.

• Added verifyOAuthQueryParams to verify signed authorization queries before rendering a custom consent page.

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

Bug Fixes

• Fixed concurrent PostgreSQL requests exceeding database-backed rate limits.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

• Fixed consumeOne deleting a record after a concurrent write invalidates its original condition.

For detailed changes, see CHANGELOG

better-auth

Features

• Added support for a bannedUserMessage function that receives the banned user, allowing sign-in errors to include details such as the ban reason.

• Added Vercel BotID as a captcha provider for protected authentication routes.

Bug Fixes

• Passwords over maxPasswordLength are now rejected with PASSWORD_TOO_LONG before hashing or verification.

• Fixed React hydration mismatches when session or plugin auth queries resolve before streamed components hydrate.

• Prevented older auth-query responses from overwriting newer results when requests overlap.

• Fixed model identity when a custom model name matches another schema key.

• Fixed schema validation for Cloudflare D1 when the Kysely dialect cannot introspect the database.

• Fixed social account linking through the OAuth Proxy plugin.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

• Fixed schema validation for SQLite-generated primary keys, including INTEGER PRIMARY KEY columns without AUTOINCREMENT.

• Fixed schema validation for Cloudflare D1 when the Kysely dialect cannot introspect the database.

For detailed changes, see CHANGELOG

@better-auth/prisma-adapter

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

• Fixed schema validation for capitalized custom Prisma model names.

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

For detailed changes, see CHANGELOG

@better-auth/memory-adapter

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

For detailed changes, see CHANGELOG

@better-auth/mongo-adapter

Bug Fixes

• Fixed model identity when a custom model name matches another schema key.

For detailed changes, see CHANGELOG

@better-auth/stripe

Bug Fixes

• Fixed automatic seat updates after an organization resubscribes, even when canceled subscriptions remain in its history.

For detailed changes, see CHANGELOG

auth

Features

• Added read-only check and check schema commands to validate your configured adapter schema on demand.

For detailed changes, see CHANGELOG

better-auth

Features

• Added database.schemaName support for direct PostgreSQL connections.

Bug Fixes

• Improved server-side logging for Cloudflare Turnstile verification failures.

• Fixed PostgreSQL migrations incorrectly identifying tables and views across schemas.

• Fixed MySQL index validation for existing string columns.

• Removed the unused optional better-sqlite3 peer dependency to prevent installation conflicts.

For detailed changes, see CHANGELOG

@better-auth/core

Features

• Added database.schemaName support for direct PostgreSQL connections.

Bug Fixes

• Fixed database option type inference outside Cloudflare Workers.

For detailed changes, see CHANGELOG

@better-auth/cimd

Bug Fixes

• Fixed unnecessary pacing of consecutive CIMD OAuth requests when metadata cannot be cached.

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

Bug Fixes

• Fixed lazy database initialization when using Drizzle relations.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Features

• Added database.schemaName support for direct PostgreSQL connections.

For detailed changes, see CHANGELOG

@better-auth/test-utils

Features

• Added Vitest 5 support to the testing utilities.

For detailed changes, see CHANGELOG

@better-auth/test-utils

Bug Fixes

• Improved adapter test suite performance by avoiding redundant cleanup queries.

• Updated adapter test suites to remove issuer-specific account requirements.

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

Bug Fixes

• Fixed async context loss in Cloudflare Workers bundles with multiple runtime conditions.

• Fixed auth request logs to respect the configured logger, log level, and disabled setting.

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

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

• Added synchronous and optional access to the current auth endpoint context.

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Bug Fixes

• Fixed Client ID Metadata Document registration when clients share at least one supported grant with the server.

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

• Fixed relative redirect URLs containing fragments.

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

Bug Fixes

• Fixed one-to-one Drizzle relations when usePlural is enabled.

• Added validation for missing Drizzle schema fields in compound where clauses.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

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

For detailed changes, see CHANGELOG

@better-auth/sso

Bug Fixes

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

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

Bug Fixes

• Fixed case-insensitive parsing of string Boolean values for SCIM User active and the primary sub-attribute of emails, phoneNumbers, addresses, roles, and entitlements at the HTTP ingress, improving Microsoft Entra interoperability.

• Added an optional SCIM-owned connection and credential catalog: configure managedConnections to allow trusted server code to create runtime tenant connections and issue, rotate, and revoke bearer credentials through server-only auth.api methods, without a code-defined connection or an application-owned verifier.

• Fixed an issue where trusted server code could not retain a terminal connection binding before a dynamic SCIM connection's first authenticated request when supplying a provisioning domain during decommissioning.

For detailed changes, see CHANGELOG

@better-auth/sso

Bug Fixes

• Fixed SSO provider registration to allow reusing a SCIM connection ID, as SCIM connections no longer participate in the authentication provider namespace.

• Fixed SAML assertion signature verification to validate signatures on the raw assertion instead of trusting an already-parsed response, and enforced signing policy and size limits on SP metadata. wantAssertionsSigned now correctly controls whether the SP requires signed assertions, matching real-world IdP signing behavior.

For detailed changes, see CHANGELOG

@better-auth/cimd

Bug Fixes

• Fixed Client ID Metadata Document caching to follow shared-cache freshness rules: the plugin now prefers s-maxage over max-age and Expires, honors s-maxage=0, conditionally revalidates with ETag or Last-Modified, and treats invalid or duplicate freshness directives as immediately stale. Concurrent refreshes now converge on a single client-resource link instead of failing on a unique constraint.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

• Fixed native adapter transactions for raw database instances (better-sqlite3, node:sqlite, bun:sqlite, mysql2, pg) passed directly as database, matching the behavior of the explicit { db }/{ dialect } config shapes. Plugins requiring native transactions (such as @better-auth/scim) now work correctly when using the quickstart database: new Database(...) form.

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Bug Fixes

• Fixed scope error responses so MCP clients now receive a 403 with an RFC 6750 insufficient_scope WWW-Authenticate challenge naming every missing scope, allowing clients to request all needed scopes in a single authorization request.

For detailed changes, see CHANGELOG

auth

Bug Fixes

• Fixed the CLI to refuse adding required columns without default values to already-populated tables

For detailed changes, see CHANGELOG

Blog post: Better Auth 1.7

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

• Added the OAuth device authorization grant (RFC 8628)

• Added DPoP sender-constrained access tokens (RFC 9449)

• Added the at_hash claim to ID tokens issued alongside an access token, per OIDC Core §3.1.3.6

• Added private_key_jwt client authentication for token endpoint requests (RFC 7523)

• Sent Cache-Control: no-store on every OAuth response that carries credentials

• Added per-request additionalParams and loginHint across signIn.social, linkSocial, and signIn.sso

• Added a server-trusted OAuth state channel, fixing anonymous account linking in in-app browsers

• Allowed passing userId and organizationId to the listUserTeams API

• Added organization.getOrganization() for metadata-only fetches

• Added a server-only consumePhoneNumberOTP API for custom phone OTP flows

• Added JWKS-backed asymmetric JWTs for the session cookie cache

• Added transactional OIDC user resolution for SSO sign-ins

• Added an immutable username option

• Allowed omitting the username plugin's separate displayUsername field

Bug Fixes

• Allowed test instances to enable native database transactions for PostgreSQL and MySQL.

• Refreshed bundled dependencies (jose, nanostores, the noble crypto packages, and SimpleWebAuthn) to their latest compatible releases. These updates are backward compatible and require no changes to existing projects.

• Widened the drizzle-kit peer dependency range

• Decoupled the session cookie cache from JWT plugin internals

• Allowed auth migrate to add required columns with static defaults and nullable unique columns to existing tables

• Bound the ID token nonce to the authorization request in the generic OAuth redirect flow

• Fixed a sign-up deadlock when JWT cookie caching ran on a single-connection SQLite database with native transactions

• Created new OAuth accounts inside the user creation transaction

• Derived the OAuth redirect_uri from the per-request base URL in multi-host deployments

• Preserved previously granted account.scope values across re-authentication and token refresh

• Preserved the resolved OAuth user when overrideUserInfo returns null

• Fired session-delete hooks and revoked bound OAuth tokens for preserved sessions on secondaryStorage

• Issued SIWE nonces before the wallet address and chain ID are known

• Fixed client plugin composition so One Tap, Electron, and Expo type-check with createAuthClient

• Single-sourced HTTP Basic credential encoding and decoding for OAuth client authentication

For detailed changes, see CHANGELOG

@better-auth/oauth-provider

Breaking Changes

• 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

  Aligned OAuth client registration and metadata with MCP authorization 2026-07-28

  Migration: Add applicationType and nullable clientDiscoveryId columns, deduplicate existing (clientId, resourceId) links before the new compound unique index, then drop the legacy type and public columns. Replace clientCredentialGrantDefaultScopes with per-client clientCredentialsScopes, backfilling every client to `` and reassigning approved machine scopes after an audit. mcp() no longer enables unauthenticated DCR: compose it with cimd() or enable both DCR flags explicitly.

• breaking

  Enforced the max_age authorization request parameter

  Migration: Users who authenticated longer ago than the requested max_age are now sent back to log in, and the ID token's auth_time reflects the fresh login. Flows that relied on max_age being ignored will prompt again.

• breaking

  Made ID token claim authority explicit, reserving OIDC protocol claims for the provider

  Migration: customIdTokenClaims, extension claims, and per-issuance idTokenClaims can no longer set protocol claims such as issuer, subject, audience, nonce, auth_time, acr, amr, or azp; use namespaced custom claims instead. ID tokens now carry acr: "0" and discovery advertises only "0".

• 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

  Bound OAuth client authentication to the grant being issued

  Migration: Remove grantType from provider.authenticateClient(...), and return { clientId, confirmation? } from a custom OAuthClientAuthenticationStrategy.authenticate instead of a client record.

• breaking

  Bound RFC 8707 resource indicators to the authorization grant

  Migration: Token and refresh requests may only narrow the authorization's resource; a broader request returns invalid_target. customAccessTokenClaims now receives a resources array in place of the resource string. Run the schema migration to add the new resource columns.

• breaking

  Returned RFC-compliant OAuth error envelopes from validation failures

  Migration: Authorization errors now redirect to a registered client's trusted redirect URI with state and iss instead of rendering the server error page, and confidential clients must use their registered token_endpoint_auth_method.

• 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.

Features

• Added token endpoint client authentication configuration across the OAuth stack

• Added the @better-auth/cimd Client ID Metadata Document plugin

• Added the OAuth device authorization grant (RFC 8628)

• Added DPoP sender-constrained access tokens (RFC 9449)

• Added an extension surface for registering grants, client authentication methods, discovery metadata, and claim contributors

• Added a refresh token reuse interval that replays the same response for duplicate refresh requests

• Allowed confidential DCR clients to complete authorization-code flows without PKCE

• Added the at_hash claim to ID tokens issued alongside an access token, per OIDC Core §3.1.3.6

• Made token introspection consistent across opaque and JWT tokens and scoped it to the audience

• Exposed the issuing sessionId to id_token claim contributors

• Honored requested UserInfo claims through a claim registry

• removed

  Removed the silenceWarnings option and the well-known endpoint warnings it suppressed

• Added protected dynamic client registration using RFC 7591 initial access tokens

• Added private_key_jwt client authentication for token endpoint requests (RFC 7523)

• Sent Cache-Control: no-store on every OAuth response that carries credentials

• Added a server-trusted OAuth state channel, fixing anonymous account linking in in-app browsers

Bug Fixes

• Enforced RFC 8628 request cardinality and client authentication on the device flow endpoints

• Accepted the OpenID Provider issuer as the aud of private_key_jwt client assertions

• Accepted UserInfo bearer tokens sent in a form-encoded request body

• Allowed nonce-bound confidential clients to request offline_access without PKCE

• Returned a 401 invalid_token challenge from /oauth2/userinfo for invalid tokens

• Completed the RP-initiated logout flow with form-encoded POST support and confirmation pages

• Deferred token revocation and back-channel logout delivery until the session deletion commits

• Accepted form-encoded POST authorization requests and rejected unsupported OIDC request objects

• Handled voluntary and essential acr claim requests per OIDC Core

• Kept profile and email scope claims on the UserInfo response instead of ID tokens

• Made the private_key_jwt jti single-use atomic across processes

• Made redirect_uri conditional at the token endpoint, required only when the authorization included one

• Preserved client key metadata and the requested authentication method during dynamic client registration

• Redirected authorization requests missing response_type to the verified client redirect URI

• Rejected authorization code replay with invalid_grant and revoked tokens issued from that code

• Reported unsupported_token_type when revoking a JWT access token

• Required the openid scope for authorization requests that use the claims parameter

• Returned invalid_grant when a client presents a refresh token issued to another client

• MCP clients that hit a scope wall now learn exactly which scopes to ask for: missing protected scopes produce a 403 with an RFC 6750 insufficient_scope challenge naming every one of them, so clients can request them in a single authorization redirect.

• Single-sourced HTTP Basic credential encoding and decoding for OAuth client authentication

For detailed changes, see CHANGELOG

@better-auth/core

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

  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

  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

  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

• 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 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

• Added an includeGrantedScopes option to the Google provider

• Added DPoP sender-constrained access tokens (RFC 9449)

• Added private_key_jwt client authentication for token endpoint requests (RFC 7523)

• Sent Cache-Control: no-store on every OAuth response that carries credentials

• Added per-request additionalParams and loginHint across signIn.social, linkSocial, and signIn.sso

• Added JWKS-backed asymmetric JWTs for the session cookie cache

• Added transactional OIDC user resolution for SSO sign-ins

Bug Fixes

• security

  Routed CIMD client_id SSRF checks through the shared host classifier, which now rejects IPv4-compatible IPv6, the 6to4 relay prefix, and site-local addresses

• Derived the OAuth redirect_uri from the per-request base URL in multi-host deployments

• Preserved previously granted account.scope values across re-authentication and token refresh

• Fixed client plugin composition so One Tap, Electron, and Expo type-check with createAuthClient

• Single-sourced HTTP Basic credential encoding and decoding for OAuth client authentication

For detailed changes, see CHANGELOG

@better-auth/sso

Breaking Changes

• breaking

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

  Migration: Accounts now require Account.issuer. SSO subjects are protocol-defined (sub for OIDC, signed NameID for SAML) and mapping.id is removed; a manual SAML config without metadata XML must set idpMetadata.entityID. Apply the account-identity backfill in the 1.7 upgrade guide before deploying.

• breaking

  Added rolling SAML certificate rotation by accepting an array of IdP signing certificates

  Migration: getSSOProvider, listSSOProviders, and updateSSOProvider now always return samlConfig.certificate as an array, so drop any Array.isArray branching. Registration rejects SAML configs with no signing-cert source with CERT_SOURCE_MISSING.

• breaking

  Hardened the validateUserInfo source contract so it cannot be bypassed or spoofed

  Migration: createUser now fails closed when validateUserInfo is configured but no endpoint context or provisioning source is available. Read SSO metadata from source.sso instead of source.oauth, and handle the source.method values sso-oidc and sso-saml.

• breaking

  Hardened SAML response validation for InResponseTo, audience restriction, and SessionIndex

  Migration: allowIdpInitiated now defaults to false. Set saml.allowIdpInitiated: true to keep accepting unsolicited SAML responses.

• breaking

  Consolidated the SAML ACS endpoint, made spMetadata optional, and fixed Single Logout

  Migration: Point your IdP's ACS URL at /sso/saml2/sp/acs/:providerId; /sso/saml2/callback/:providerId is removed. callbackUrl is now the post-auth redirect only, and the unused decryptionPvk, additionalParams, idpMetadata.entityURL, and idpMetadata.redirectURL fields are gone.

Features

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

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

• Added private_key_jwt client authentication for token endpoint requests (RFC 7523)

• Added per-request additionalParams and loginHint across signIn.social, linkSocial, and signIn.sso

• Added a server-trusted OAuth state channel, fixing anonymous account linking in in-app browsers

• Added transactional OIDC user resolution for SSO sign-ins

• Extended resolveUser to SAML sign-ins and hardened the provider lifecycle

• Added additionalFields support on ssoProvider

Bug Fixes

• Allowed an SSO provider registration to reuse a SCIM connection ID, since SCIM connections no longer share the authentication provider namespace.

• Rejected redirecting OIDC discovery, token, userinfo, and JWKS endpoints so SSO works on Cloudflare Workers

• Updated samlify to 2.13.1 for a signed-assertion XML injection fix

• Upgraded samlify to 2.12.0 with XPath injection and XXE fixes

• Single-sourced HTTP Basic credential encoding and decoding for OAuth client authentication

• Verified SAML assertion signatures directly instead of trusting an already-parsed response, and applied the same signing policy and size limit to SP metadata as to IdP metadata. wantAssertionsSigned now controls whether signed assertions are required rather than signed response messages, matching how IdPs sign SAML responses in practice.

For detailed changes, see CHANGELOG

@better-auth/scim

Breaking Changes

• 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

  Isolated SCIM provider connections from the organization and SSO plugins

  Migration: Define connections statically, resolve them with authentication.verifyBearerToken, or use the optional managedConnections catalog, and connect SCIM resources to users and roles through identity and projection callbacks. Legacy SCIM state is not migrated: back it up, issue new credentials, and fully reprovision Users and Groups.

• breaking

  Bound personal SCIM connections to their creator and removed user-session connection management

  Migration: The legacy connection management endpoints and providerOwnership are gone, so authorize SCIM administration in your own application. Legacy scimProvider rows and credentials are not migrated: follow the 1.7 SCIM upgrade guide, issue new credentials, and reprovision Users and Groups.

Features

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

• Added durable SCIM Group resources with connection-scoped membership and lifecycle endpoints

• Added the SCIM Enterprise User extension and the standard User attributes for interop conformance

• Added a managed connection catalog and runtime connection resolution

• Added acquireActiveSCIMUserLink for transaction-safe authentication of provisioned users

Bug Fixes

• Accepted exact case-insensitive string boolean values for SCIM User active and the primary sub-attribute of emails, phoneNumbers, addresses, roles, and entitlements at the HTTP ingress, for Microsoft Entra interoperability.

• Added an optional SCIM-owned connection and credential catalog. Configure managedConnections so trusted server code can create runtime tenant connections and issue, rotate, and revoke their bearer credentials through server-only auth.api methods, without a code-defined connection or an application-owned verifier.

• Allowed trusted server code to retain a terminal connection binding before a dynamic SCIM connection's first authenticated request by supplying its provisioning domain during decommissioning.

• Created filtered SCIM PATCH values when no target matches instead of rejecting the request

For detailed changes, see CHANGELOG

@better-auth/mcp

Breaking Changes

• 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

  Aligned OAuth client registration and metadata with MCP authorization 2026-07-28

  Migration: Add applicationType and nullable clientDiscoveryId columns, deduplicate existing (clientId, resourceId) links before the new compound unique index, then drop the legacy type and public columns. Replace clientCredentialGrantDefaultScopes with per-client clientCredentialsScopes, backfilling every client to `` and reassigning approved machine scopes after an audit. mcp() no longer enables unauthenticated DCR: compose it with cimd() or enable both DCR flags explicitly.

• breaking

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

  Migration: mcp() now requires an explicit resource identifier, for example resource: "https://api.example.com/mcp". validAudiences is removed: move each resource identifier into resources. Run npx @better-auth/cli generate and apply the migration before deploying.

Features

• Added DPoP sender-constrained access tokens (RFC 9449)

• Added a refresh token reuse interval that replays the same response for duplicate refresh requests

For detailed changes, see CHANGELOG

@better-auth/electron

Breaking Changes

• 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

  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.

Bug Fixes

• Fixed client plugin composition so One Tap, Electron, and Expo type-check with createAuthClient

For detailed changes, see CHANGELOG

@better-auth/expo

Breaking Changes

• breaking

  Switched Expo secure storage to async access so apps no longer crash when the iOS Keychain is unavailable

  Migration: getCookie() now returns a promise, and custom storage implementations must provide both synchronous and asynchronous SecureStore methods. storageAdapter.setItem() stays synchronous, so use setItemAsync() when the write must be awaited.

• 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.

Bug Fixes

• Fixed client plugin composition so One Tap, Electron, and Expo type-check with createAuthClient

For detailed changes, see CHANGELOG

@better-auth/stripe

Breaking Changes

• breaking

  Made the event parameter of onSubscriptionCancel required

  Migration: Declare event as a required parameter in your callback and remove any undefined guards around it.

• breaking

  Removed the optional marker from the onSubscriptionCancel event parameter

  Migration: event is always supplied, so drop undefined handling from the callback.

For detailed changes, see CHANGELOG

auth

Breaking Changes

• breaking

  Accumulated OAuth granted scopes in a new grantedScopes string array

  Migration: grantedScopes replaces the comma-joined account.scope string with no read-time fallback, so backfill it from the existing values. The client provider contract is renamed from OAuthProvider to UpstreamProvider.

Features

• Added a create-admin command for creating an initial admin user

• Added compound table indexes to plugin database schemas

Bug Fixes

• Preserved issuer-scoped account identities by restoring Account.accountId alongside the required issuer

• Exported the generated pgSchema binding so drizzle-kit can emit CREATE SCHEMA for custom PostgreSQL namespaces

• Loaded the auth config through c12 v4 resolveModule, adding support for the export default { auth } shape

• Reverted the granted scopes architecture, restoring the previous account.scope storage

For detailed changes, see CHANGELOG

@better-auth/drizzle-adapter

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 } }, and regenerate the schema (npx auth@latest generate) so it includes the required relations.

Features

• Added compound table indexes to plugin database schemas

• Added a relations-v2 entry point for projects using Drizzle Relations v2

• Added a schemaName option that generates the Drizzle schema inside a pgSchema namespace

Bug Fixes

• Exported the generated pgSchema binding so drizzle-kit can emit CREATE SCHEMA for custom PostgreSQL namespaces

For detailed changes, see CHANGELOG

@better-auth/cimd

Breaking Changes

• breaking

  Aligned OAuth client registration and metadata with MCP authorization 2026-07-28

  Migration: Add applicationType and nullable clientDiscoveryId columns, deduplicate existing (clientId, resourceId) links before the new compound unique index, then drop the legacy type and public columns. Client ID Metadata Documents preserve an omitted application_type as null and cannot assign clientCredentialsScopes. Compose mcp() with cimd() for metadata-document clients.

Features

• Added the @better-auth/cimd Client ID Metadata Document plugin

Bug Fixes

• Client ID Metadata Documents now follow shared-cache freshness rules and fail closed when freshness is ambiguous. The plugin prefers s-maxage over max-age and Expires, honors s-maxage=0, revalidates conditionally with ETag or Last-Modified, and treats invalid or duplicate freshness directives as immediately stale. Concurrent refreshes converge on one client-resource link instead of failing on its unique constraint.

For detailed changes, see CHANGELOG

@better-auth/api-key

Breaking Changes

• breaking

  Hardened atomic state transitions so concurrent requests cannot race past single-use or rate-limit guards

  Migration: Custom adapters must implement native consumeOne and incrementOne, secondary storage needs atomic consume and increment operations, and custom rate-limit storage makes one consume decision per request. The read-then-delete and read-then-update fallbacks are removed.

For detailed changes, see CHANGELOG

@better-auth/kysely-adapter

Bug Fixes

• Fixed SQLite dialect bundles on Kysely 0.29 by mirroring the migration-table constants locally

• Raw database instances (better-sqlite3, node:sqlite, bun:sqlite, mysql2, pg) passed directly as database now get native adapter transactions automatically, matching the behavior of the explicit { db } and { dialect } config shapes. This unblocks plugins that require native transactions (such as @better-auth/scim) when the database is provided in the quickstart database: new Database(...) shape.

For detailed changes, see CHANGELOG

@better-auth/i18n

Features

• Added built-in translations for 22 languages

For detailed changes, see CHANGELOG

@better-auth/mongo-adapter

Features

• Added compound table indexes to plugin database schemas

For detailed changes, see CHANGELOG

@better-auth/passkey

Features

• Added an optional createSession setting that signs the user in on successful passkey registration

For detailed changes, see CHANGELOG

@better-auth/core

Bug Fixes

• Fixed database option type inference for projects that do not use Cloudflare Workers.

For detailed changes, see CHANGELOG

better-auth

Bug Fixes

• Improved diagnostics for Cloudflare Turnstile verification failures

For detailed changes, see CHANGELOG

better-auth

Features

• Added an option to disable OpenTelemetry span creation for individual auth instances

For detailed changes, see CHANGELOG

@better-auth/core

Features

• Added an option to disable OpenTelemetry span creation for individual auth instances

For detailed changes, see CHANGELOG

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

Bug Fixes

• Fixed automatic organization assignment via email domain to require both a verified provider domain and a verified stored user email, preventing social sign-in from joining an organization whose SSO provider merely claims that domain.

• Fixed domain verification to snapshot the provider's domains at request start, returning 409 with SSO_PROVIDER_CHANGED if the provider changes during DNS resolution so callers can reload and retry.

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

Bug Fixes

• Fixed automatic email-domain organization assignment to require both a verified provider domain and a verified user email, preventing social sign-in from granting access when an SSO provider merely claims a domain.

• Fixed domain verification to snapshot the provider's domains at request start, returning 409 with SSO_PROVIDER_CHANGED if the provider changes during DNS verification so callers can reload and retry.

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

Bug Fixes

• Restored client plugin declaration compatibility for downstream TypeScript consumers

For detailed changes, see the CHANGELOG.

@better-auth/expo

Bug Fixes

• 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/scim

Bug Fixes

• Fixed auth endpoint types to align with better-call

For detailed changes, see CHANGELOG

auth

Bug Fixes

• Fixed the CLI to align installed packages with the running CLI version

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

Features

• Added a utility for creating stable, namespaced placeholder emails on the reserved placeholder.invalid domain

For detailed changes, see CHANGELOG

@better-auth/redis-storage

Bug Fixes

• Fixed listKeys() and clear() to use SCAN instead of KEYS so large keyspaces no longer block the Redis server

For detailed changes, see CHANGELOG