Guides

Role‑Based Access

Protect routes using generic field matching on AuthUser.

Use this guide when your Better Auth user shape includes fields such as role, teamRole, or custom authorization flags and you want to use them in route rules or server checks.

With Admin Plugin

server/auth.config.ts

import { admin } from 'better-auth/plugins'
import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
export default defineServerAuth({ plugins: [admin()] })

// nuxt.config.ts - role is now typed!
routeRules: {
  '/admin/**': { auth: { user: { role: 'admin' } } },
  '/staff/**': { auth: { user: { role: ['admin', 'moderator'] } } },
}

With Organization Plugin

nuxt.config.ts

// Works the same way with any plugin fields
routeRules: {
  '/team/**': { auth: { user: { teamRole: 'owner' } } },
}

With Custom Fields

nuxt.config.ts

// Any field on AuthUser works
routeRules: {
  '/premium/**': { auth: { user: { isPremium: true } } },
  '/verified/**': { auth: { user: { emailVerified: true } } },
}

Matching Logic

Single value: exact match required
Array: OR logic (user field must be one of the values)
Multiple fields: AND logic (all must match)

// Must be admin AND verified
{ auth: { user: { role: 'admin', emailVerified: true } } }

// Must be admin OR moderator
{ auth: { user: { role: ['admin', 'moderator'] } } }

Complex Logic

For complex authorization, use custom middleware or requireUserSession with a rule callback.

Complex Authorization with Rule Callbacks

For authorization logic that can't be expressed with field matching:

server/api/reports.ts

export default defineEventHandler(async (event) => {
  await requireUserSession(event, {
    rule: (session) => {
      // User must have 'reports:read' permission
      return session.user.permissions?.includes('reports:read')
    }
  })

  return getReports()
})