Queries

Every query exposes a hook and an options factory. The factory's .queryKey is the canonical key.

import { useSession } from "@better-auth-ui/react"
import { sessionOptions } from "@better-auth-ui/core"

Use the hook in components. Use the factory where TanStack Query accepts a queryOptions object.

Read .queryKey from the factory when you add data to the cache or invalidate it.

Invalidation

All keys start with ["auth", ...]. Queries for one user use the ["auth", "user", userId, ...] prefix.

Invalidate a prefix to control the related cache entries. Use authQueryKeys from @better-auth-ui/core to create consistent keys:

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

queryClient.invalidateQueries({ queryKey: authQueryKeys.all })
queryClient.invalidateQueries({ queryKey: authQueryKeys.user(userId) })
queryClient.invalidateQueries({ queryKey: authQueryKeys.session })

Per-user queries

Settings queries use a separate cache key for each user. They wait for the session before they start.

React Query uses skipToken until userId resolves. This design removes stale data after sign-out and isolates data after an account switch.

Escape hatch

Use useAuthQuery for a read endpoint that has no specific hook. Use useAuthMutation for a mutation endpoint.

import { authClient } from "@/lib/auth-client"
import { useAuthQuery } from "@better-auth-ui/react"

const { data } = useAuthQuery(
  authClient.magicLink.list,
  ["auth", "magicLink", "list"],
  { query: { limit: 20 } }
)

options.query is appended to the key, so the cached key above is ["auth", "magicLink", "list", { limit: 20 }] (or [..., null] when omitted). Pass fetchOptions through the same options object.

For loaders, prefetchQuery, or useQueries, import the core factory directly:

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

authQueryOptions(authClient.magicLink.list, ["auth", "magicLink", "list"], {
  query: { limit: 20 }
})

Available queries

Auth

Settings

Organization