API Reference

Server Utilities

API reference for server-side helpers available in Nitro event handlers.

These utilities are only available in full mode. In clientOnly mode, there is no local auth server, so these utilities are not registered.

serverAuth

Returns the initialized Better Auth instance (module-level singleton). Pass the event for accurate URL detection on first initialization.

server/api/admin/users.get.ts

export default defineEventHandler(async (event) => {
  const auth = serverAuth(event)
  const session = await auth.api.getSession({ headers: event.headers })

  if (!session) {
    throw createError({ statusCode: 401 })
  }

  return { user: session.user }
})

You can also pass query options to bypass cookie cache / refresh behavior:

await auth.api.getSession({
  headers: event.headers,
  query: { disableCookieCache: true },
})

Use serverAuth() to access advanced Better Auth features not exposed by the helper wrappers.

getUserSession

Retrieves the current session from the request context without throwing an error if unauthenticated.

server/api/example.ts

export default defineEventHandler(async (event) => {
  const session = await getUserSession(event)
  
  if (session) {
    // ...
  }
})

Returns:

{ user: AuthUser, session: AuthSession } if authenticated.
null if unauthenticated.

requireUserSession

Ensures the user is authenticated and optionally matches specific criteria. Throws a 401 Unauthorized or 403 Forbidden error if checks fail.

const { user, session } = await requireUserSession(event, options?)

Options

user

UserMatch

Object matching user properties (see Route Protection).

rule

(ctx) => boolean | Promise<boolean>

Custom validation callback.

Examples

Role Check:

server/api/admin/dashboard.ts

await requireUserSession(event, {
  user: { role: 'admin' }
})

Custom Rule:

server/api/admin/dashboard.ts

await requireUserSession(event, {
  rule: ({ user }) => {
    return user.points > 100
  }
})

Combining User Matching with Rules

server/api/team/[teamId]/settings.ts

export default defineEventHandler(async (event) => {
  const { teamId } = getRouterParams(event)

  // Require admin role AND membership in the specific team
  await requireUserSession(event, {
    user: { role: 'admin' },
    rule: async (session) => {
      const membership = await getTeamMembership(session.user.id, teamId)
      return membership?.role === 'owner'
    }
  })

  return getTeamSettings(teamId)
})