[{"data":1,"prerenderedAt":604},["ShallowReactive",2],{"navigation_docs":3,"-core-concepts-server-auth":216,"-core-concepts-server-auth-surround":599},[4,42,68,115,136,157],{"title":5,"path":6,"stem":7,"children":8,"icon":11},"Getting Started","\u002Fgetting-started","1.getting-started\u002F0.index",[9,12,17,22,27,32,37],{"title":10,"path":6,"stem":7,"icon":11},"Introduction","i-lucide-sparkles",{"title":13,"path":14,"stem":15,"icon":16},"Installation","\u002Fgetting-started\u002Finstallation","1.getting-started\u002F1.installation","i-lucide-download",{"title":18,"path":19,"stem":20,"icon":21},"Configuration","\u002Fgetting-started\u002Fconfiguration","1.getting-started\u002F2.configuration","i-lucide-settings",{"title":23,"path":24,"stem":25,"icon":26},"Client Setup","\u002Fgetting-started\u002Fclient-setup","1.getting-started\u002F3.client-setup","i-lucide-monitor",{"title":28,"path":29,"stem":30,"icon":31},"Type Augmentation","\u002Fgetting-started\u002Ftype-augmentation","1.getting-started\u002F4.type-augmentation","i-lucide-type",{"title":33,"path":34,"stem":35,"icon":36},"Schema Generation (NuxtHub)","\u002Fgetting-started\u002Fschema-generation","1.getting-started\u002F5.schema-generation","i-lucide-database",{"title":38,"path":39,"stem":40,"icon":41},"How It Works","\u002Fgetting-started\u002Fhow-it-works","1.getting-started\u002F6.how-it-works","i-lucide-workflow",{"title":43,"path":44,"stem":45,"children":46,"page":67},"Core Concepts","\u002Fcore-concepts","2.core-concepts",[47,51,55,59,63],{"title":48,"path":49,"stem":50},"serverAuth()","\u002Fcore-concepts\u002Fserver-auth","2.core-concepts\u002F1.server-auth",{"title":52,"path":53,"stem":54},"Sessions","\u002Fcore-concepts\u002Fsessions","2.core-concepts\u002F2.sessions",{"title":56,"path":57,"stem":58},"Route Protection","\u002Fcore-concepts\u002Froute-protection","2.core-concepts\u002F3.route-protection",{"title":60,"path":61,"stem":62},"Auto‑Imports and Aliases","\u002Fcore-concepts\u002Fauto-imports-aliases","2.core-concepts\u002F4.auto-imports-aliases",{"title":64,"path":65,"stem":66},"Security & Caveats","\u002Fcore-concepts\u002Fsecurity-caveats","2.core-concepts\u002F5.security-caveats",false,{"title":69,"path":70,"stem":71,"children":72,"page":67},"Guides","\u002Fguides","3.guides",[73,77,82,86,90,94,99,103,107,111],{"title":74,"path":75,"stem":76},"Role‑Based Access","\u002Fguides\u002Frole-based-access","3.guides\u002F1.role-based-access",{"title":78,"path":79,"stem":80,"icon":81},"Setup diagnostics","\u002Fguides\u002Fdiagnostics","3.guides\u002F10.diagnostics","i-lucide-circle-alert",{"title":83,"path":84,"stem":85},"OAuth Providers","\u002Fguides\u002Foauth-providers","3.guides\u002F2.oauth-providers",{"title":87,"path":88,"stem":89},"Custom Database","\u002Fguides\u002Fcustom-database","3.guides\u002F3.custom-database",{"title":91,"path":92,"stem":93},"Database-less Mode","\u002Fguides\u002Fdatabase-less-mode","3.guides\u002F4.database-less-mode",{"title":95,"path":96,"stem":97,"icon":98},"External Auth Backend","\u002Fguides\u002Fexternal-auth-backend","3.guides\u002F5.external-auth-backend","i-lucide-server",{"title":100,"path":101,"stem":102},"Migrating from nuxt-auth-utils","\u002Fguides\u002Fmigrate-from-nuxt-auth-utils","3.guides\u002F6.migrate-from-nuxt-auth-utils",{"title":104,"path":105,"stem":106},"Two-Factor Authentication (TOTP + Backup Codes)","\u002Fguides\u002Ftwo-factor-auth","3.guides\u002F7.two-factor-auth",{"title":108,"path":109,"stem":110},"Testing","\u002Fguides\u002Ftesting","3.guides\u002F8.testing",{"title":112,"path":113,"stem":114},"Production Deployment","\u002Fguides\u002Fproduction-deployment","3.guides\u002F9.production-deployment",{"title":116,"path":117,"stem":118,"children":119,"page":67},"Integrations","\u002Fintegrations","4.integrations",[120,124,128,132],{"title":121,"path":122,"stem":123},"NuxtHub","\u002Fintegrations\u002Fnuxthub","4.integrations\u002F1.nuxthub",{"title":125,"path":126,"stem":127},"DevTools","\u002Fintegrations\u002Fdevtools","4.integrations\u002F2.devtools",{"title":129,"path":130,"stem":131},"Convex","\u002Fintegrations\u002Fconvex","4.integrations\u002F3.convex",{"title":133,"path":134,"stem":135},"i18n","\u002Fintegrations\u002Fi18n","4.integrations\u002F4.i18n",{"title":137,"path":138,"stem":139,"children":140,"page":67},"API Reference","\u002Fapi","5.api",[141,145,149,153],{"title":142,"path":143,"stem":144},"Composables","\u002Fapi\u002Fcomposables","5.api\u002F1.composables",{"title":146,"path":147,"stem":148},"Server Utilities","\u002Fapi\u002Fserver-utils","5.api\u002F2.server-utils",{"title":150,"path":151,"stem":152},"Components","\u002Fapi\u002Fcomponents","5.api\u002F3.components",{"title":154,"path":155,"stem":156},"Types","\u002Fapi\u002Ftypes","5.api\u002F4.types",{"title":158,"path":159,"stem":160,"children":161,"icon":81},"Errors","\u002Ferrors","6.errors\u002F0.index",[162,164,168,172,176,180,184,188,192,196,200,204,208,212],{"title":163,"path":159,"stem":160},"Overview",{"title":165,"path":166,"stem":167},"Better Auth CLI is not installed","\u002Ferrors\u002Fnuxt-auth-cli-missing","6.errors\u002Fnuxt-auth-cli-missing",{"title":169,"path":170,"stem":171},"Better Auth CLI version does not match better-auth","\u002Ferrors\u002Fnuxt-auth-cli-version-mismatch","6.errors\u002Fnuxt-auth-cli-version-mismatch",{"title":173,"path":174,"stem":175},"Auth configuration failed to load","\u002Ferrors\u002Fnuxt-auth-config-load-failed","6.errors\u002Fnuxt-auth-config-load-failed",{"title":177,"path":178,"stem":179},"Schema generator returned no code","\u002Ferrors\u002Fnuxt-auth-empty-schema","6.errors\u002Fnuxt-auth-empty-schema",{"title":181,"path":182,"stem":183},"Invalid server auth config export","\u002Ferrors\u002Fnuxt-auth-invalid-config-export","6.errors\u002Fnuxt-auth-invalid-config-export",{"title":185,"path":186,"stem":187},"Auth plugin path must be absolute","\u002Ferrors\u002Fnuxt-auth-invalid-plugin-source","6.errors\u002Fnuxt-auth-invalid-plugin-source",{"title":189,"path":190,"stem":191},"Missing auth configuration","\u002Ferrors\u002Fnuxt-auth-missing-config","6.errors\u002Fnuxt-auth-missing-config",{"title":193,"path":194,"stem":195},"NuxtHub database alias is missing","\u002Ferrors\u002Fnuxt-auth-missing-hub-db","6.errors\u002Fnuxt-auth-missing-hub-db",{"title":197,"path":198,"stem":199},"No database provider is enabled","\u002Ferrors\u002Fnuxt-auth-no-database-provider","6.errors\u002Fnuxt-auth-no-database-provider",{"title":201,"path":202,"stem":203},"Auth schema generation failed","\u002Ferrors\u002Fnuxt-auth-schema-generation-failed","6.errors\u002Fnuxt-auth-schema-generation-failed",{"title":205,"path":206,"stem":207},"Custom session storage is missing","\u002Ferrors\u002Fnuxt-auth-schema-storage-required","6.errors\u002Fnuxt-auth-schema-storage-required",{"title":209,"path":210,"stem":211},"Secondary storage in client-only mode","\u002Ferrors\u002Fnuxt-auth-storage-client-only","6.errors\u002Fnuxt-auth-storage-client-only",{"title":213,"path":214,"stem":215},"Unsupported database dialect","\u002Ferrors\u002Fnuxt-auth-unsupported-dialect","6.errors\u002Fnuxt-auth-unsupported-dialect",{"id":217,"title":48,"body":218,"description":593,"extension":594,"links":595,"meta":596,"navigation":248,"path":49,"seo":597,"stem":50,"__hash__":598},"docs\u002F2.core-concepts\u002F1.server-auth.md",{"type":219,"value":220,"toc":589},"minimark",[221,292,296,328,399,404,521,526,529,533,572,585],[222,223,224],"code-collapse",{},[225,226,232],"pre",{"className":227,"code":228,"filename":229,"language":230,"meta":231,"style":231},"language-txt shiki shiki-themes one-light synthwave-84 synthwave-84","Use server-side auth utilities in @nuxtjs\u002Fbetter-auth.\n\n- `serverAuth(event?)` — returns the Better Auth instance. Pass `event` in Nitro handlers for request-scoped database access and configuration context\n- `getUserSession(event)` — get current session (auto-imported in `server\u002F`)\n- `requireUserSession(event, options?)` — throws 401 if not authenticated, supports role matching\n- `getRequestSession(event)` — request-cached session, preferred over repeated `getUserSession` in same request\n- `setRequestSession(event, session)` — supply an authenticated session to downstream helpers for the current request\n- `refreshSessionCookieCache(event)` — refresh Better Auth's cached session cookie after server-side session data changes\n- All server utils are auto-imported, no import statements needed\n","Prompt","txt","",[233,234,235,243,250,256,262,268,274,280,286],"code",{"__ignoreMap":231},[236,237,240],"span",{"class":238,"line":239},"line",1,[236,241,242],{},"Use server-side auth utilities in @nuxtjs\u002Fbetter-auth.\n",[236,244,246],{"class":238,"line":245},2,[236,247,249],{"emptyLinePlaceholder":248},true,"\n",[236,251,253],{"class":238,"line":252},3,[236,254,255],{},"- `serverAuth(event?)` — returns the Better Auth instance. Pass `event` in Nitro handlers for request-scoped database access and configuration context\n",[236,257,259],{"class":238,"line":258},4,[236,260,261],{},"- `getUserSession(event)` — get current session (auto-imported in `server\u002F`)\n",[236,263,265],{"class":238,"line":264},5,[236,266,267],{},"- `requireUserSession(event, options?)` — throws 401 if not authenticated, supports role matching\n",[236,269,271],{"class":238,"line":270},6,[236,272,273],{},"- `getRequestSession(event)` — request-cached session, preferred over repeated `getUserSession` in same request\n",[236,275,277],{"class":238,"line":276},7,[236,278,279],{},"- `setRequestSession(event, session)` — supply an authenticated session to downstream helpers for the current request\n",[236,281,283],{"class":238,"line":282},8,[236,284,285],{},"- `refreshSessionCookieCache(event)` — refresh Better Auth's cached session cookie after server-side session data changes\n",[236,287,289],{"class":238,"line":288},9,[236,290,291],{},"- All server utils are auto-imported, no import statements needed\n",[293,294,295],"p",{},"Use this page when you need authentication state or Better Auth APIs inside Nitro handlers, middleware, plugins, or other server-side code.",[293,297,298,301,302,305,306,309,310,313,314,316,317,320,321,324,325,327],{},[233,299,300],{},"serverAuth(event?)"," returns the Better Auth instance. Pass ",[233,303,304],{},"event"," in Nitro handlers for request-scoped database access and ",[233,307,308],{},"ctx.requestOrigin",". In production, the canonical auth URL comes from ",[233,311,312],{},"runtimeConfig.public.siteUrl"," or platform environment variables. Development can infer it from the request. Outside request contexts, such as seed scripts and tasks, call ",[233,315,48],{}," without an event. On Nuxt 4.6+, when the auth secret is derived from ",[233,318,319],{},"NUXT_APP_SECRET",", it is resolved asynchronously: the module starts it when the server starts and awaits it in its handlers, middleware, and session utilities. Code that runs at server startup, such as a Nitro plugin, should use ",[233,322,323],{},"await ensureServerAuth()",", which waits for the secret and then returns the same instance as ",[233,326,48],{},".",[225,329,334],{"className":330,"code":331,"filename":332,"language":333,"meta":231,"style":231},"language-ts shiki shiki-themes one-light synthwave-84 synthwave-84","export default defineNitroPlugin(async () => {\n  const auth = await ensureServerAuth()\n  \u002F\u002F ...\n})\n","server\u002Fplugins\u002Fseed.ts","ts",[233,335,336,366,388,394],{"__ignoreMap":231},[236,337,338,342,346,350,354,357,360,363],{"class":238,"line":239},[236,339,341],{"class":340},"sqe1H","export",[236,343,345],{"class":344},"sKg8T"," default",[236,347,349],{"class":348},"sfT9l"," defineNitroPlugin",[236,351,353],{"class":352},"s17Py","(",[236,355,356],{"class":340},"async",[236,358,359],{"class":352}," () ",[236,361,362],{"class":340},"=>",[236,364,365],{"class":352}," {\n",[236,367,368,371,375,379,382,385],{"class":238,"line":245},[236,369,370],{"class":340},"  const",[236,372,374],{"class":373},"s6Rhl"," auth",[236,376,378],{"class":377},"sQBpM"," =",[236,380,381],{"class":340}," await",[236,383,384],{"class":348}," ensureServerAuth",[236,386,387],{"class":352},"()\n",[236,389,390],{"class":238,"line":252},[236,391,393],{"class":392},"st7cf","  \u002F\u002F ...\n",[236,395,396],{"class":238,"line":258},[236,397,398],{"class":352},"})\n",[400,401,403],"h2",{"id":402},"when-to-use-what","When to Use What",[405,406,407,423],"table",{},[408,409,410],"thead",{},[411,412,413,417,420],"tr",{},[414,415,416],"th",{},"Task",[414,418,419],{},"Use",[414,421,422],{},"Example",[424,425,426,440,453,466,479,492,508],"tbody",{},[411,427,428,432,437],{},[429,430,431],"td",{},"Get request-cached session context",[429,433,434],{},[233,435,436],{},"getRequestSession(event)",[429,438,439],{},"Cache once per request with context-backed storage when available",[411,441,442,445,450],{},[429,443,444],{},"Supply a request session",[429,446,447],{},[233,448,449],{},"setRequestSession(event, session)",[429,451,452],{},"Reuse a session resolved by trusted server authentication",[411,454,455,458,463],{},[429,456,457],{},"Get current session",[429,459,460],{},[233,461,462],{},"getUserSession(event)",[429,464,465],{},"Check if user is logged in",[411,467,468,471,476],{},[429,469,470],{},"Refresh cached session cookie",[429,472,473],{},[233,474,475],{},"refreshSessionCookieCache(event)",[429,477,478],{},"Use after updating data returned by Better Auth session helpers",[411,480,481,484,489],{},[429,482,483],{},"Require authentication",[429,485,486],{},[233,487,488],{},"requireUserSession(event)",[429,490,491],{},"Protect an API route",[411,493,494,497,502],{},[429,495,496],{},"Access Better Auth API",[429,498,499],{},[233,500,501],{},"serverAuth(event)",[429,503,504,505],{},"Call ",[233,506,507],{},"auth.api.listSessions()",[411,509,510,513,518],{},[429,511,512],{},"Get session with options",[429,514,515],{},[233,516,517],{},"requireUserSession(event, { user: { role: 'admin' } })",[429,519,520],{},"Role-based protection",[293,522,523,525],{},[233,524,475],{}," refreshes the cached session cookie. It does not update the session or user record; perform that update first.",[527,528],"read-more",{"to":147},[400,530,532],{"id":531},"server-endpoint-path","Server endpoint path",[293,534,535,536,539,540,543,544,547,548,551,552,555,556,558,559,562,563,565,566,568,569,571],{},"The module registers Better Auth at ",[233,537,538],{},"\u002Fapi\u002Fauth"," within the Nuxt app. If ",[233,541,542],{},"app.baseURL"," is ",[233,545,546],{},"\u002Fapp\u002F",", the public endpoints and generated callback URLs use ",[233,549,550],{},"\u002Fapp\u002Fapi\u002Fauth",". ",[233,553,554],{},"defineServerAuth"," accepts only ",[233,557,538],{}," as ",[233,560,561],{},"basePath"," and rejects other values when resolving the config. Remove a custom server ",[233,564,561],{}," or set it to ",[233,567,538],{},"; the module includes ",[233,570,542],{}," automatically.",[293,573,574,575,578,579,581,582,327],{},"External backends configured with ",[233,576,577],{},"auth.clientOnly: true"," can still use a custom ",[233,580,561],{}," in ",[233,583,584],{},"defineClientAuth",[586,587,588],"style",{},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sqe1H, html code.shiki .sqe1H{--shiki-light:#A626A4;--shiki-default:#FEDE5D;--shiki-dark:#FEDE5D}html pre.shiki code .sKg8T, html code.shiki .sKg8T{--shiki-light:#E45649;--shiki-default:#FEDE5D;--shiki-dark:#FEDE5D}html pre.shiki code .sfT9l, html code.shiki .sfT9l{--shiki-light:#4078F2;--shiki-default:#36F9F6;--shiki-dark:#36F9F6}html pre.shiki code .s17Py, html code.shiki .s17Py{--shiki-light:#383A42;--shiki-default:#BBBBBB;--shiki-dark:#BBBBBB}html pre.shiki code .s6Rhl, html code.shiki .s6Rhl{--shiki-light:#986801;--shiki-default:#FF7EDB;--shiki-dark:#FF7EDB}html pre.shiki code .sQBpM, html code.shiki .sQBpM{--shiki-light:#0184BC;--shiki-default:#FFFFFFEE;--shiki-dark:#FFFFFFEE}html pre.shiki code .st7cf, html code.shiki .st7cf{--shiki-light:#A0A1A7;--shiki-light-font-style:italic;--shiki-default:#848BBD;--shiki-default-font-style:italic;--shiki-dark:#848BBD;--shiki-dark-font-style:italic}",{"title":231,"searchDepth":245,"depth":245,"links":590},[591,592],{"id":402,"depth":245,"text":403},{"id":531,"depth":245,"text":532},"When to reach for the full Better Auth server instance.","md",null,{},{"title":48,"description":593},"OG3cMivIiR0raRbf-x6iwz1oQA5NMp0SIE2IVtyF35U",[600,602],{"title":38,"path":39,"stem":40,"description":601,"icon":41,"children":-1},"Understand the architecture after completing setup.",{"title":52,"path":53,"stem":54,"description":603,"children":-1},"Access reactive session state with SSR support using `useUserSession()`.",1792535506084]