Core Concepts
serverAuth()
When to reach for the full Better Auth server instance.
Prompt
Use server-side auth utilities in @onmax/nuxt-better-auth.
- `serverAuth(event?)` — returns the Better Auth instance. Pass `event` in Nitro handlers for request-aware base URLs
- `getUserSession(event)` — get current session (auto-imported in `server/`)
- `requireUserSession(event, options?)` — throws 401 if not authenticated, supports role matching
- `getRequestSession(event)` — request-cached session, preferred over repeated `getUserSession` in same request
- `refreshSessionCookieCache(event)` — refresh Better Auth's cached session cookie after server-side session data changes
- All server utils are auto-imported, no import statements needed
Use this page when you need authentication state or Better Auth APIs inside Nitro handlers, middleware, plugins, or other server-side code.
serverAuth(event?) returns the Better Auth instance (module-level singleton). In Nitro handlers, you should pass event so the module can resolve request-aware base URLs on initialization. Outside request contexts (seed scripts, tasks, plugins), you can call serverAuth() without an event.
When to Use What
| Task | Use | Example |
|---|---|---|
| Get request-cached session context | getRequestSession(event) | Cache once per request with context-backed storage when available |
| Get current session | getUserSession(event) | Check if user is logged in |
| Refresh cached session cookie | refreshSessionCookieCache(event) | Use after updating data returned by Better Auth session helpers |
| Require authentication | requireUserSession(event) | Protect an API route |
| Access Better Auth API | serverAuth(event) | Call auth.api.listSessions() |
| Get session with options | requireUserSession(event, { user: { role: 'admin' } }) | Role-based protection |
refreshSessionCookieCache(event) refreshes the cached session cookie. It does not update the session or user record; perform that update first.