Queries

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

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

Use the hook in components. Use the factory anywhere TanStack Query takes a queryOptions object (useQuery, useQueries, prefetchQuery, loaders). Read .queryKey off the factory for cache seeding or invalidation.

Invalidation

Keys follow an ["auth", ...] prefix, with per-user queries nested under ["auth", "user", userId, ...]. Invalidate by prefix for hierarchical cache control. Use the shared authQueryKeys factory from @better-auth-ui/core so cache entries line up regardless of which options factory produced them:

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 (useListAccounts, useAccountInfo, useListSessions, useListDeviceSessions, useListPasskeys, useListApiKeys) are keyed per-user and wait for the active session before firing — queryFn is swapped for skipToken until userId resolves. This means they drop out of the cache cleanly on sign-out and on account switching with a persister they stay isolated per user.

Escape hatch

For read-style endpoints without a purpose-built hook, use useAuthQuery (or its options factory authQueryOptions). Mutation-style endpoints should use useAuthMutation instead.

import { useAuth, useAuthQuery } from "@better-auth-ui/react"

const { authClient } = useAuth()
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, use the factory directly:

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

Available queries

Auth

Settings

Organization