Server-side session in Astro
In Astro, retrieve session using auth.api.getSession({ headers: Astro.request.headers }).
client apis
137 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Client-side getSession method
Call authClient.getSession() to retrieve session data on the client side. It returns an object with data (session) and error properties.
Server-side session in TanStack
In TanStack Start, retrieve session using auth.api.getSession({ headers: request.headers }) in an API route.
Server-side session in Svelte
In Svelte, retrieve session in a +page.ts load function using auth.api.getSession({ headers: request.headers }).
Server-side session in Hono
In Hono, retrieve session using auth.api.getSession({ headers: c.req.raw.headers }) in a route handler.
Server-side session in Nuxt
In Nuxt, retrieve session using auth.api.getSession({ headers: event.headers }) within an event handler.
Server-side session retrieval
Call auth.api.getSession with a headers object to retrieve session data on the server side. The headers parameter is required and should be passed from the request context.
Server-side session in Next.js
In Next.js, retrieve session using auth.api.getSession({ headers: await headers() }) where headers is imported from 'next/headers'.
useSession hook returns session data and utilities
The authClient.useSession hook returns an object with properties: data (session), isPending (loading state), error, and refetch (function to refetch session). It is implemented using nanostore and supports React, Vue, Svelte, Solid, and Vanilla.
Better Auth client sign-in after Auth0 migration
After migrating from Auth0, use Better Auth client for sign-in: authClient.signIn.email({ email, password }). This returns { data, error } tuple. Check for error before handling successful sign in.
useSession hook example for browser extension popup
The useSession hook from authClient can be used in a React component to access session data. It returns an object with data, isPending, and error properties. Example: const {data, isPending, error} = authClient.useSession(); Check isPending for loading state, error for errors, and data.user for user information when authenticated.
Create auth client for browser extension
Create a file at src/auth/auth-client.ts using createAuthClient from better-auth/react. Pass baseURL pointing to your Better Auth backend (e.g., http://localhost:3000) and an empty plugins array: import { createAuthClient } from "better-auth/react"; export const authClient = createAuthClient({ baseURL: "http://localhost:3000", plugins: [], });
authClient.signIn.email for email password authentication
The Better Auth client provides authClient.signIn.email method which takes email and password parameters and returns an object with data and error properties.
getSessionCookie function for Better Auth middleware
Use `getSessionCookie` imported from 'better-auth/cookies' to check for active sessions in middleware. It takes a NextRequest parameter and returns the session cookie if present.
MCP createMcpAuthClient renamed to createMcpResourceClient
`createMcpAuthClient` is renamed `createMcpResourceClient` in the MCP client API.
Client-side resource protection pattern
To protect a resource on the client-side, use authClient.useSession() to get session data with isPending state. Check if data exists and error is null before showing content; otherwise redirect to sign-in page. During loading (isPending true), show a loading state.
Server-side get session
Getting the current session on the server-side uses auth.api.getSession() method which requires headers from Next.js. The call is: await auth.api.getSession({ headers: await headers() }).
Server-side resource protection pattern
To protect a resource on the server-side, call auth.api.getSession({ headers: await headers() }) and check if the session exists. If no session, use redirect() to send user to sign-in page. Otherwise, proceed with rendering the protected content.
Creating Better Auth client instance
The client instance for Better Auth is created by importing createAuthClient from 'better-auth/react' and calling it without arguments. This returns a client that provides functions for interacting with the Better Auth server instance.
Better Auth Next.js route handler setup
The Better Auth route handler for Next.js is set up in /app/api/auth/[...all]/route.ts by importing auth from the auth file and toNextJsHandler from 'better-auth/next-js'. The route exports POST and GET handlers created by calling toNextJsHandler(auth).
Client-side get session with useSession hook
Getting the current session on the client-side uses authClient.useSession() hook. It returns an object with data (session data), error, refetch, isPending, and isRefetching properties.
Next.js caching with use cache directive
In Next.js v15 and later, use the 'use cache' directive in server functions to cache the response. This directive is placed as a string statement at the start of the function body.
TanStack Query caching with useQuery
With TanStack Query, use the useQuery hook to cache data. The hook accepts a cache key string, an async fetch function, and an options object. The staleTime option sets the cache duration in milliseconds.
React Router v7 caching with Cache-Control headers
In React Router v7, cache responses using HTTP Cache-Control headers in the loader function and export a headers function to send these headers. The example shows 'Cache-Control': 'max-age=3600' for caching 1 hour.
SolidStart caching with query function
In SolidStart, use the query function to cache data. The query function takes an async function and a cache key string as arguments.
Server-side session retrieval in Next.js
To get the session server-side in Next.js, call auth.api.getSession passing headers from the 'next/headers' import. Returns a session object with user property or null if not authenticated.
Creating API route in Next.js
Create an API route at /app/api/auth/[...all]/route.ts that exports POST and GET handlers by calling toNextJsHandler(auth) from 'better-auth/next-js'.
Client-side session retrieval in Better Auth
To get the session client-side, use authClient.useSession() which returns an object with data (session), error, and isPending properties. Redirect if no session exists.
Creating Better Auth client instance
Create a client instance using createAuthClient from 'better-auth/react' with optional plugins that require a client.
Middleware auth check in Next.js 15+
For convenience-based middleware auth checks in Next.js 15+ with Node.js runtime, import NextRequest and NextResponse from 'next/server', get headers, call auth.api.getSession with those headers, and redirect if no session exists. Configure matcher to specify which routes the middleware applies to.
dashClient and sentinelClient web client configuration
Web clients are configured by importing `dashClient` and `sentinelClient` from `@better-auth/infra/client`. The `sentinelClient` accepts an `autoSolveChallenge` option (boolean) that automatically solves proof-of-work challenges when set to true.
Web client example with dashClient and sentinelClient
Example web client configuration: ```ts import { createAuthClient } from "better-auth/client"; import { dashClient, sentinelClient } from "@better-auth/infra/client"; export const authClient = createAuthClient({ plugins: [ dashClient(), sentinelClient({ autoSolveChallenge: true, }), ], }); ```
dashClient and sentinelNativeClient for Expo and React Native
For Expo or React Native clients, import from `@better-auth/infra/native` instead of `@better-auth/infra/client`. This entry provides `dashClient` (with the same audit log APIs as the web client) and `sentinelNativeClient`. The `sentinelNativeClient` also accepts an `autoSolveChallenge` option.
Example: getAllAuditLogs() filter by organization
const orgActivity = await authClient.dash.getAllAuditLogs({ session: session.data, organizationId: "org_123", });
getAuditLogs() - returns current user's audit events
The getAuditLogs() method returns audit events for the current user only. Use this for end-user activity and organization views where the caller is a normal member. Required parameter: session (object with user). Optional parameters: limit (number, max 100, default 50), offset (number, default 0), organizationId (string), identifier (string), eventType (string), userId (string), user (object with ID).
Example: getAllAuditLogs() pagination
async function fetchAllAuditLogs(session: unknown) { const limit = 100; let offset = 0; const allEvents = []; while (true) { const result = await authClient.dash.getAllAuditLogs({ session: session.data, limit, offset, }); const events = result.data?.events ?? []; allEvents.push(...events); if (events.length < limit) break; offset += limit; } return allEvents; }
dashClient() setup for auth client
To access audit logs on the client, add dashClient() plugin to createAuthClient. This enables audit log query methods like getAuditLogs() and getAllAuditLogs().
Example: getAllAuditLogs() combined filters
const orgEvents = await authClient.dash.getAllAuditLogs({ session: session.data, organizationId: "org_123", eventType: "member_invited", });
Example: getAllAuditLogs() filter by event type
const events = await authClient.dash.getAllAuditLogs({ session: session.data, eventType: "member_invited", });
Example: getAllAuditLogs() filter by user
const userActivity = await authClient.dash.getAllAuditLogs({ session: session.data, userId: "user_456", });
Example: getAllAuditLogs() basic query
const session = await authClient.getSession(); const activity = await authClient.dash.getAllAuditLogs({ session: session.data, limit: 50, offset: 0, }); activity.data?.events; activity.data?.total; activity.data?.limit; activity.data?.offset;
Example: getAuditLogs() with identifier filter
const orgSignIns = await authClient.dash.getAuditLogs({ session: session.data, organizationId: "org_123", identifier: "user@example.com", });
Audit log response structure
Both getAuditLogs() and getAllAuditLogs() return response.data object containing: events (array of audit log events), total (total count of events), limit (page size), offset (current pagination offset).
getAllAuditLogs() - returns admin audit events
The getAllAuditLogs() method returns all audit events for organizations the current user has admin or owner access to. Use for admin dashboards showing activity across organizations you manage. Requires organization plugin for membership role evaluation. Required parameter: session (object with user). Optional parameters: limit (number, max 100, default 50), offset (number, default 0), organizationId (string), userId (string), eventType (string), identifier (string, matches eventData.identifier for organization-scoped actor identity).
getAllAuditLogs() client method
The authClient.dash.getAllAuditLogs() method returns all audit events for organizations where the current user has admin or owner access. Requires the organization plugin for role checks. It accepts session (required), limit (number), and offset (number) parameters. Returns an object with data containing events (array) and total (count).
dashClient() plugin installation and import
The dashClient plugin is imported from @better-auth/infra/client and added to the client plugins array. For Expo or React Native, import dashClient from @better-auth/infra/native instead.
getAuditLogs() client method
The authClient.dash.getAuditLogs() method returns audit events for the current user or organization-scoped events when organizationId is passed. It accepts session (required), limit (number), and offset (number) parameters. Returns an object with data containing events (array), total (count), limit (page size), and offset (current offset).
dashClient() resolveUserId configuration
The dashClient() plugin accepts a resolveUserId function that receives an object with userId, user, and session properties. It should return a custom user ID value, allowing logic like: `return userId || user?.id || session?.user?.id;`
sentinelClient browser fingerprinting
sentinelClient automatically includes a visitor ID in requests via the X-Visitor-Id header. This fingerprint is used for credential stuffing detection, free trial abuse prevention, and device tracking.
sentinelClient configuration for web
sentinelClient() is used on the client side for web applications. Configuration includes autoSolveChallenge (boolean, default true) to automatically solve PoW challenges, and kvTimeout (number, default 1000) for timeout in ms for KV identify and related HTTP requests. Import sentinelClient from @better-auth/infra/client.
Sentinel client example for Expo
import { createAuthClient } from "better-auth/react"; import { expoClient } from "@better-auth/expo/client"; import { dashClient, sentinelNativeClient } from "@better-auth/infra/native"; import * as SecureStore from "expo-secure-store"; export const authClient = createAuthClient({ baseURL: "https://your-api.example.com", plugins: [ expoClient({ scheme: "myapp", storagePrefix: "myapp", storage: SecureStore, }), dashClient(), sentinelNativeClient({ autoSolveChallenge: true, }), ], });
Sentinel client example for React Native
import { createAuthClient } from "better-auth/client"; import { dashClient, sentinelNativeClient } from "@better-auth/infra/native"; export const authClient = createAuthClient({ baseURL: "https://your-api.example.com", plugins: [ dashClient(), sentinelNativeClient({ autoSolveChallenge: true, }), ], });
Sentinel client example for web
import { createAuthClient } from "better-auth/client"; import { sentinelClient } from "@better-auth/infra/client"; export const authClient = createAuthClient({ plugins: [ sentinelClient({ autoSolveChallenge: true, }), ], });
sentinelNativeClient options table
sentinelNativeClient has these configuration options: - identifyUrl (string): KV identify endpoint base URL. Default: BETTER_AUTH_KV_URL environment variable, then https://kv.better-auth.com - kvTimeout (number): Timeout in ms for KV identify and related HTTP requests. Default: 1000 - autoSolveChallenge (boolean): On 423 with X-PoW-Challenge, solve and retry once with X-PoW-Solution. Default: true - onChallengeReceived ((reason: string) => void, optional): Called when a PoW challenge is received - onChallengeSolved ((solveTimeMs: number) => void, optional): Called after a successful solve - onChallengeFailed ((error: Error) => void, optional): Called if solving fails - storage ({ getItem, setItem }, optional): Persistent async storage for a stable per-install visitor ID. Default: Async Storage when installed
sentinelNativeClient for Expo and React Native
For Expo and React Native apps, use sentinelNativeClient from @better-auth/infra/native instead of sentinelClient. For React Native apps, install peer dependencies: @react-native-async-storage/async-storage (optional but recommended for production) and react-native-get-random-values. If @react-native-async-storage/async-storage is not installed, the client uses a session-only in-memory visitor ID.
sentinelClient PoW solution header
When auto-solving is enabled in sentinelClient, solved challenges are sent via the X-PoW-Solution header.
SvelteKit handler setup
For SvelteKit, add the following to `hooks.server.ts`: `import { auth } from '$lib/auth'; import { svelteKitHandler } from 'better-auth/svelte-kit'; import { building } from '$app/environment'; export async function handle({ event, resolve }) { return svelteKitHandler({ event, resolve, auth, building }); }`
Nuxt handler setup
For Nuxt, create a file at `/server/api/auth/[...all].ts` with the following code: `import { auth } from '~/utils/auth'; export default defineEventHandler((event) => { return auth.handler(toWebRequest(event)); });`
Next.js Pages Router handler setup
For Next.js Pages Router, create a file at `/pages/api/auth/[...all].ts` with the following code: `import { auth } from '@/lib/auth'; import { toNodeHandler } from 'better-auth/node'; export const config = { api: { bodyParser: false } }; export default toNodeHandler(auth.handler);` Disallow body parsing as Better Auth will parse it manually.
Next.js App Router handler setup
For Next.js App Router, create a file at `/app/api/auth/[...all]/route.ts` with the following code: `import { auth } from '@/lib/auth'; import { toNextJsHandler } from 'better-auth/next-js'; export const { POST, GET } = toNextJsHandler(auth);`