Better Auth release notes, breaking changes, and upgrade notes.
The most comprehensive authentication framework for TypeScript StackPulse turns upstream changelogs into scannable summaries with risky changes, deprecations, migration notes, and source links.
This prerelease adds DPoP-bound OAuth requests and pushed authorization requests, alongside changes to client-assertion audience validation and Generic OAuth discovery issuer checks. It also includes numerous OAuth-provider behavior and schema changes that require migration or application updates; the supplied notes are truncated before all changes are listed.
affected
OAuth-provider and Generic OAuth integrations may require assertion-audience, discovery, UserInfo, claim-handling, database-schema, or custom API updates; users of read replicas must also ensure they read their own writes for verification data.
action
Review the release's action-required notes and apply the relevant database migrations and OAuth integration updates before upgrading.
release_signals
-Client assertions such as `private_key_jwt` now use the authorization server's issuer as their sole `aud` by default when known; endpoint-URL audiences are rejected unless compatibility is configured.
-Generic OAuth now checks the discovery document's `issuer` against `discoveryUrl` and skips providers whose issuer does not match.
-UserInfo rejects Authorization headers without a `Bearer` or `DPoP` scheme and returns `403 insufficient_scope` when the token lacks the `openid` scope.
-An `undefined` claim value no longer removes a same-named claim from a lower-priority source; use a value such as `null` when removal is intended.
-The `expectedAudience` strategy input and parameter are deprecated in favor of `acceptedAudiences`.
!Deprecated `expectedAudience` in favor of `acceptedAudiences` for client authentication strategies and `consumeClientAssertion`.
migration_steps5 steps
01For CIBA users, run `npx auth@latest migrate`, or generate and apply the ORM schema, to add `acrValues` and `authorizationDetails` to `cibaRequest`.
02For OAuth-provider users, add `requirePushedAuthorizationRequests` to `oauthClient` before deployment; use the migration command or generate and apply the ORM schema.
03For OAuth-provider users, add `accessTokenClaims` to `oauthAccessToken` using the migration command or generated ORM schema.
04For `oauthProvider()` users, add `grantId` columns to `oauthRefreshToken` and `oauthAccessToken` before deployment.
05If using custom `OAuthProviderApi` implementations, add the `challengeDpopNonce()` method.
This release fixes cross-origin header exposure, DPoP failures involving secondary storage, OAuth provider behavior, and authorization URL query encoding. It also changes how `oauthProviderResourceClient(auth)` obtains signing keys; set `jwksUrl` if you want it to continue fetching them over HTTP.
affected
Users of the OAuth provider resource client that depend on HTTP JWKS fetching must configure `jwksUrl`; OAuth provider and core users also benefit from fixes to browser header access, DPoP, logout, token introspection, and authorization URLs.
action
Set `jwksUrl` if your resource client must continue fetching signing keys over HTTP.
release_signals
-`oauthProviderResourceClient(auth)` no longer necessarily fetches signing keys over HTTP; set `jwksUrl` to preserve HTTP key fetching.
migration_steps1 steps
v1.7.23mediumbreakingmigrationfeatureNov 13, 2026
v1.7.23
This release fixes OAuth/MCP authentication behavior, including JWKS retrieval, DPoP scope challenges, cross-origin visibility of authentication challenges, and authorization-code handling when validation fails. It also resolves bugs affecting Electron sign-in callbacks, database adapters, and parallel MongoDB tests; no security vulnerability or CVE is identified in the notes.
affected
Applications using MCP authentication, custom CORS exposure, or DPoP in multi-instance/serverless deployments may need configuration changes; users of the listed adapters and Electron integration receive bug fixes.
action
Apply the release's three MCP/CORS/DPoP configuration steps if they match your deployment, and upgrade to receive the fixes.
release_signals
-For `requireMcpAuth` to continue fetching signing keys over HTTP, configure `jwksUrl`; without it, the prior fetching behavior may no longer work.
This prerelease adds OAuth token-exchange delegation with RFC 8693 actor tokens, expands DPoP support, and corrects sender-constrained token handling. SSO changes allow users to sign in when their OIDC or SAML provider does not send an email, while tightening how SAML NameID is interpreted. The release includes upgrade actions for OAuth provider and custom API users, as well as SAML configurations affected by the updated email mapping behavior.
affected
OAuth provider integrators, clients using DPoP or other sender-constrained tokens, custom OAuth provider API implementations, and SAML/OIDC deployments with providers that omit email may need to adjust configuration or code.
action
Before upgrading, complete the applicable OAuth schema migration and review the listed DPoP, token-exchange, and SAML email changes for your integrations.
This prerelease adds server-provided DPoP nonce support and makes OAuth client-secret expiration persist and be enforced. It introduces single-use server-issued nonces for client-submitted ID tokens and Google One Tap, and tightens OAuth Authorization-header handling; these changes include breaking behavior and required database migration steps for some adapters.
affected
Applications using generic OAuth Authorization headers, client-submitted provider ID tokens, Google One Tap callbacks, OAuth provider client secrets, or affected database adapters may need configuration or schema updates.
action
Review the OAuth and One Tap breaking changes and apply the documented adapter migration before deploying; enable `requireIssuedIdTokenNonce` only if the application is prepared to issue and submit nonces.
This release fixes issues across OAuth, SSO, database adapters, SCIM, and Cloudflare Workers, including token refresh behavior, SAML replay protection, and intermittent startup failures. It also changes Prisma `update` to affect only one matching row and requires native adapter transactions for SCIM provisioning; MongoDB index build failures now require correcting the underlying cause before restarting.
affected
Applications using SCIM with adapters lacking native transactions, MongoDB index creation, or Prisma updates on non-unique filters are directly affected; OAuth, SSO, and Cloudflare Workers users also receive relevant fixes.
action
Review the listed SCIM, MongoDB index, and Prisma update action items before upgrading.
release_signals
-Prisma adapter `update` now changes only one matching row; use `updateMany` when all rows matching a non-unique filter must be changed.
This prerelease changes OAuth authorization handling so repeated parameters in form-encoded POST requests follow the same rules as GET requests. It also adds binding of a client's own token exchange to its DPoP key.
affected
OAuth provider clients that submit repeated standard parameters in form-encoded POST authorization requests are affected; clients sending each standard parameter once are unaffected.
action
Check OAuth clients for repeated standard parameters in form-encoded POST authorization requests and update them to send each standard parameter once.
release_signals
-Form-encoded POST authorization requests to `/oauth2/authorize` now reject repeated standard parameters with `invalid_request`; previously, the last value could be used and a code could be issued.
This prerelease changes authentication and session validation behavior across Better Auth, Electron, passkey, core, and OAuth provider packages. Key changes include requiring active stored sessions for sensitive operations when server-side session storage is enabled, stricter phone-number verification and password-reset rules, and updated handling of two-factor sign-in and passkey user verification.
affected
Integrators using phone authentication, passkeys, two-factor authentication, Electron sign-in, OAuth linking, device-code approval, or server-side session storage may need to adjust configuration or callback handling.
action
Review the listed breaking changes and update affected hooks, phone OTP configuration, and session-dependent flows before upgrading.
release_signals
-With a server-side session store, passkey registration, device-code approval, two-factor enrollment, phone number changes, social account linking, and organization invitations now require a session that is still active in the store, even when cookie caching is enabled. Electron code exchange also requires the issuing browser session to remain active.
This release fixes authentication and authorization issues across Better Auth and its provider, passkey, Expo, Electron, and Stripe packages. Key fixes prevent revoked or unverified sessions and identities from being accepted, bind verification and authorization flows to the correct account or browser session, and tighten origin and role checks. It also changes the permission required for admin phone-number updates and how server code sets Stripe customer IDs.
affected
Applications using Better Auth’s admin phone updates, Stripe integration, session caching, OAuth, passkeys, or desktop and mobile authorization flows may be affected by these fixes and behavior changes.
action
Review custom access-control statements and any server-side Stripe customer ID updates, then upgrade to v1.7.16.
release_signals
-Admin phone-number updates now require the `user:set-phone` permission; custom access-control statements must include `set-phone` to allow this operation.
This prerelease changes Paybin and Twitch to fetch current user profile data through their OAuth endpoints using access tokens, rather than relying on stored ID-token claims. Spotify profile fields were also updated to match its current user profile, requiring mappings to account for nullable or omitted fields.
affected
Integrations using Paybin, Twitch, or Spotify profile mappings are affected, especially custom Paybin or Twitch ID-token sign-ins that use the default profile reader.
action
Review affected provider profile mappings and add `idToken.accessToken` to custom Paybin and Twitch ID-token sign-ins using the default `getUserInfo`.
release_signals
-Paybin now uses its published `/oauth/*` endpoints and returns UserInfo data instead of stored ID-token claims. Profile mappings must handle omitted email; custom ID-token sign-ins using the default profile reader must provide `idToken.accessToken`.
This prerelease updates OAuth profile types and handling across numerous providers to better match official provider responses, including optional, nullable, or retyped claims. It also changes Slack userinfo requests to POST and improves handling of scoped profiles and HTTP-200 error responses; the release flags these compatibility changes as breaking.
affected
Applications using OAuth profile types or custom mappings for the listed providers may need changes to remain compatible with provider responses and updated Better Auth behavior.
action
Review and update any custom OAuth profile mappings or types for the affected providers, especially where claims may now be optional, nullable, or retyped.
release_signals
-OAuth profile types and runtime handling changed across Apple, Cognito, Discord, Dropbox, Facebook, GitHub, GitLab, Gumroad, Linear, Microsoft Entra ID, Notion, Patreon, PayPal, Railway, Slack, and Twitter(X). Custom profile mappings or types may need updates for fields that are now optional, nullable, or retyped.
!
The release requires renaming custom `ba_sub` claims, according to the action-required notes.
+Added `createDpopFetch` with per-origin nonce handling and one retry on `use_dpop_nonce`.
+Added a `dpop: { keyPair }` option for Generic OAuth providers to request DPoP-bound tokens (RFC 9449).
+Added pushed authorization requests (RFC 9126) to Generic OAuth sign-in through `pushedAuthorizationRequest`.
+Added `endpointType` and issuer information to custom token endpoint authentication hooks and client assertion getters.
+Added `deriveEncryptionKey(secret, purpose)` for deriving purpose-specific encryption keys.
01
If you want `oauthProviderResourceClient(auth)` to keep fetching signing keys over HTTP, set `jwksUrl`.
01Set `jwksUrl` if `requireMcpAuth` needs to fetch signing keys over HTTP.
02If your CORS layer sets `Access-Control-Expose-Headers`, add `WWW-Authenticate` so browser clients can read authentication challenges.
03For `createMcpProtectedRequestHandler` in multi-instance or serverless deployments, configure `dpop.replayStore` with a shared store, such as `createDpopReplayStore(internalAdapter)`.
OAuth token exchange now supports delegation and handles the `act` claim differently: `act` set through custom access-token claims contributors or resource custom claims is stripped; custom grants should pass it to `issueTokens` instead.
-Clients using DPoP-bound tokens must send a DPoP proof with each request to protected resources.
-Custom `OAuthProviderApi` implementations must add `verifyDpopProof()` and `issueDpopNonce()`.
-SAML NameID is used as the user's email only when its Format is `emailAddress`; configurations relying on other or unspecified NameID formats must provide or map an email.
+Added RFC 8693 delegation to `oauthTokenExchange()`, supporting `actor_token` and an `act` claim.
+Added `expectedJkt` to `provider.resolveConfirmation()` to preserve DPoP key binding in extension grants.
+Added `verifyDpopProof()` and `issueDpopNonce()` to the OAuth provider API for plugin endpoints.
+Added `mapProfileToUser` for OIDC and SAML SSO providers that do not send an email.
migration_steps5 steps
01OAuth provider users: run `npx auth@latest migrate` or `npx auth@latest generate` before upgrading to add the optional `act` column on `oauthAccessToken`.
02If a SAML IdP sends no email attribute and uses a non-`emailAddress` or unspecified NameID Format, send an `email` attribute or use the `emailAddress` NameID Format, set `samlConfig.mapping.email` to the supplied attribute, or return the NameID from `mapProfileToUser`.
03If `clientAuthentication` returns a DPoP key (`jkt`), ensure clients send a DPoP proof with every request to a protected resource.
04Update custom `OAuthProviderApi` implementations to provide `verifyDpopProof()` and `issueDpopNonce()`.
05For client token exchanges bound by a mechanism other than DPoP, such as mTLS, have `clientAuthentication` return the same `confirmation`.
Generic OAuth now fails at startup if `authorizationHeaders` includes `Authorization`; token request functions throw if `headers` includes `authorization`. Configure credentials through `customizeRequest` with `tokenEndpointAuth` method `custom`, setting all credentials required by the provider.
-ID-token sign-in and account linking can require server-issued single-use nonces when `requireIssuedIdTokenNonce` is enabled; requests without an issued nonce or with a reused nonce are rejected. Built-in verification rejects opaque tokens when a nonce is also supplied.
-`/one-tap/callback` now requires a single-use nonce obtained from `POST /one-tap/nonce`; client-provided nonce configuration must be removed.
!Single-use server-issued nonces bind client-submitted ID tokens to a request and prevent token reuse when the option is enabled; Google One Tap callbacks also require a single-use nonce.
!OAuth provider client-secret expiry is now saved, returned as `client_secret_expires_at`, and enforced with `invalid_client` at token, introspection, and revocation endpoints.
+Added server-provided DPoP nonce support for OAuth providers and resource servers, including `dpop: { nonce: { required: true } }`, `verifyAccessTokenRequest`, `createResourceServerChallenge`, and `createDpopNonce`.
+Added optional server-issued, single-use nonce binding for client-submitted provider ID tokens via `requireIssuedIdTokenNonce`.
+Added `POST /one-tap/nonce` for single-use nonce binding in Google One Tap callbacks.
migration_steps3 steps
01For generic OAuth, remove `Authorization` from `authorizationHeaders` and remove `authorization` from token-function `headers`; set the header using `customizeRequest` with `tokenEndpointAuth` method `custom`, including every provider-required credential.
02For manually invoking `/one-tap/callback` or `auth.api.oneTapCallback`, call `POST /one-tap/nonce`, pass the value to `google.accounts.id.initialize({ nonce })`, and send it as `nonce` in the callback body; remove client `nonce` and `additionalOptions.nonce` settings.
03For the built-in Kysely adapter, run `npx auth@latest migrate`. For Prisma or Drizzle, run `npx auth@latest generate` and apply the migration before deploying to add `expiresAt` to `oauthClient`; MongoDB requires no migration.
-SCIM provisioning of users and groups requires an adapter with native transactions; `/scim/v2` requests return 501 on adapters without them.
!SIWE verification no longer exposes internal error messages in 401 responses; details are logged server-side.
!SAML replay protection now rejects a signed response resubmitted with its assertion ID encoded as XML character references in the specified configurations.
!OAuth provider fixes revoke in-flight access tokens on adapters without foreign keys and return `invalid_grant` when reuse revokes an in-flight issuance.
+Cloudflare Workers are detected and reported as `workerd` by core telemetry, and runtime detection is exported from `@better-auth/core/env`.
+SCIM now handles groups with more than 100 members.
migration_steps3 steps
01For SCIM user and group provisioning, switch to an adapter with native transactions; adapters without them return 501 for `/scim/v2` requests.
02If relying on `update` to change every row matching a non-unique filter, use `updateMany` instead.
03If a MongoDB index build fails due to duplicate values, missing `createIndex` permission, or a conflicting index on the same field, fix the cause and restart.
-Phone number verification now requires ownership of the account holding the unverified number; sign-up and sign-in reject a phoneNumber with PHONE_NUMBER_CANNOT_BE_SET. Phone password reset works only for a number already verified on the account.
-Credential sign-in after-hooks now run after the built-in two-factor challenge and receive a null new session while verification is pending.
-When authenticatorSelection.userVerification is required, passkey authentication rejects responses without user verification.
-Phone sign-in with requireVerification requires sendOTP to be configured; otherwise the route returns SEND_OTP_NOT_IMPLEMENTED.
migration_steps5 steps
01Update credential sign-in after-hooks to handle a null new session while two-factor verification is pending.
02If using phone sign-in with requireVerification, configure sendOTP.
03Ensure phone password resets are initiated only for phone numbers already verified on the account.
04If calling linkOAuthAccount directly, pass the session that started the link in OAuth state.
05Account for active stored-session requirements on the affected operations when server-side session storage is enabled.
Sign-up and update-user requests can no longer set `stripeCustomerId`; server code must set it through the database adapter instead.
!Fixed revoked sessions remaining usable with secondary storage or cookie caching, and added session-store checks to sensitive flows.
!Prevented unverified phone numbers and incorrectly verified OAuth email claims from being accepted; bound verification links and codes to the intended account.
!Fixed email OTP attempt limits under concurrent requests and tightened organization role, invitation, and trusted-origin checks.
!Fixed the Expo authorization proxy accepting server-unissued state or redirecting to unconfigured providers, and bound Electron authorization codes to the issuing browser session.
!Fixed passkey origin validation to use server configuration and enforced required user verification during registration and authentication.
migration_steps2 steps
01Add `set-phone` to custom access-control statements if they should permit `/admin/update-user` to change phone numbers.
02If server code sets `stripeCustomerId` through `auth.api.updateUser`, change it to write through the database adapter.
-Twitch now fetches current profile data with access tokens instead of stored ID-token claims. Profile mappings must handle optional fields; custom ID-token sign-ins using the default profile reader must provide `idToken.accessToken`.
-Spotify profile fields now reflect the current user profile: display names and image dimensions can be nullable, email can be omitted, and a missing display name leaves the local name unset while raw profile fields remain available.
migration_steps2 steps
01For custom Twitch and Paybin ID-token sign-ins using the default `getUserInfo`, include `idToken.accessToken`; standard redirect-based sign-in requires no changes.
02Update Paybin, Twitch, and Spotify profile mappings to handle the optional, omitted, or nullable fields described in the release notes.
-Slack sign-in now uses POST for userinfo in the built-in provider and Generic OAuth helper, supports scoped profiles with optional email and profile claims, and rejects Slack errors returned with HTTP 200.
-Provider-specific behavior and types changed, including GitLab and Linear preserving stored images when provider avatars are null during profile updates, and Cognito checking both documented issuer formats.
migration_steps1 steps
01If you use custom profile mappings or profile types for any of the listed OAuth providers, review the updated provider claims and adjust handling for fields that are now optional, nullable, or retyped.