Mutations

Every mutation exposes an options factory. The factory's .mutationKey is the canonical key.

import { signInEmailOptions } from "@better-auth-ui/solid"

Use the factory anywhere Solid Query takes a mutationOptions object — createMutation, global mutation state checks, or a MutationCache observer. Organization mutations additionally expose use* hooks for component code because they need provider-scoped invalidation metadata.

Error handling

Every mutation wires throw: true into fetchOptions, so the promise rejects with a BetterFetchError on failure instead of resolving with { error }. This means you can rely on error, isError, throwOnError, and standard onError handlers from createMutation.

import { signInEmailOptions } from "@better-auth-ui/solid"
import { createMutation } from "@tanstack/solid-query"

const signIn = createMutation(() => ({
  ...signInEmailOptions(authClient),
  onError: (err) => toast.error(err.message)
}))

Cache side effects

Factories that change auth state set up the same shared mutation keys as React. Apply cache side effects in your mutation handlers, or use the Organization hooks where available so AuthProvider can consume their invalidation metadata.

Common side effects mirror the React docs:

• signInEmailOptions / signInUsernameOptions / signInPasskeyOptions / signUpEmailOptions — reset the session query so the new session is refetched. (signInSocialOptions and signInMagicLinkOptions redirect instead, so they leave the cache alone.)
• signOutOptions — remove every ["auth", ...] query.
• updateUserOptions — merge or refetch the cached session after a successful profile update.
• setActiveSessionOptions — update the active session and refetch session/device-session queries.
• changeEmailOptions — refetch the session.
• addPasskeyOptions / deletePasskeyOptions — refetch the passkey list.
• revokeSessionOptions — refetch the sessions list.
• revokeMultiSessionOptions — refetch the device sessions list.
• unlinkAccountOptions — refetch the linked accounts list.
• Organization hook mutations expose invalidation metadata consumed by AuthProvider, so organization/member/invitation queries are invalidated with the same shared cache keys.

The Solid package does not render toast UI. Attach success/error handling in your app, or use installed Zaidan components that already integrate with the app's toast surface.

Tracking mutation state globally

All mutation keys are prefixed with "auth" and exposed through the shared authMutationKeys factory in @better-auth-ui/core. Use it instead of inlining tuples so call sites share the same source of truth as the mutation factories:

import { authMutationKeys } from "@better-auth-ui/core"

const authPending = queryClient.isMutating({
  mutationKey: authMutationKeys.all
})
const signInPending = queryClient.isMutating({
  mutationKey: authMutationKeys.signIn.all
})
const emailSignInPending = queryClient.isMutating({
  mutationKey: authMutationKeys.signIn.email
})

Each grouping (signIn, signUp, passkey, multiSession) exposes an all prefix so you can match a whole feature at once.

Match inside a MutationCache observer for global toasts or analytics:

import { authMutationKeys } from "@better-auth-ui/core"
import { MutationCache } from "@tanstack/solid-query"

new MutationCache({
  onError: (error, _vars, _ctx, mutation) => {
    if (mutation.options.mutationKey?.[0] === authMutationKeys.all[0]) {
      toast.error(error.message)
    }
  }
})

Escape hatch

For write-style endpoints without a purpose-built factory or hook, use useAuthMutation in components or authMutationOptions where Solid Query takes mutation options. Read-style endpoints should use useAuthQuery instead.

import { useAuthMutation } from "@better-auth-ui/solid"

const mutation = useAuthMutation(
  authClient.emailOtp.sendVerificationOtp,
  ["auth", "emailOtp", "sendVerificationOtp"]
)

mutation.mutate({ email: "[email protected]", type: "sign-in" })

Variables are inferred from authFn's parameter — required params reject mutate() at the type level, optional-param methods (e.g. signOut) allow it. throw: true is wired into fetchOptions so onError and error get a BetterFetchError.

For shared mutation registration, global mutation state checks, a MutationCache observer, or manual createMutation, use the factory directly:

authMutationOptions(authClient.emailOtp.sendVerificationOtp, [
  "auth",
  "emailOtp",
  "sendVerificationOtp"
])

For endpoints that already have a key in authMutationKeys, prefer it over an inline tuple so cache observers and mutation state checks line up.

Available mutations

Auth

Settings

Organization