Adding Admin feature

Better Auth, which we already use for authentication in this boilerplate, offers a complete plugin system to extend its features.

The library provides a specific plugin for managing admin users with features like role-based access control, user impersonation, and ban management. The official Better Auth documentation covers this plugin and all its options in depth.

This guide will help you quickly configure the Admin plugin in the boilerplate with NestJS and MikroORM.

File Structure

Since the Admin plugin is part of Better Auth and works as an integrated system, we will add all admin-related fields to existing files in the /auth folder.

Here is the file structure we will modify:

apps/api/src/
├── modules/auth/
│   ├── auth.entity.ts              (to update)
│   └── auth.config.ts              (to update)

Installation

1. Add the plugin to Better Auth configuration

   In your Better Auth configuration file apps/api/src/modules/auth/auth.config.ts on the API side, add the admin plugin:

   import { admin } from 'better-auth/plugins'
   
   export const auth = betterAuth({
     // ... your existing config
     plugins: [
       admin({
         defaultRole: 'user',
         adminRoles: ['admin'],
       }),
     ],
   })

   Configuration options

   • defaultRole: The default role assigned to new users (e.g., ‘user’)
   • adminRoles: Array of role names that should have admin privileges (e.g., [‘admin’, ‘superadmin’])
   
   

2. Update the User entity

   The Admin plugin adds several fields to the user table. Update your User entity in auth.entity.ts:

   apps/api/src/modules/auth/auth.entity.ts

   @Entity({ tableName: 'user' })
   export class User {
     // ... your existing properties (id, name, email, etc.)
   
     @Property()
     role!: string
   
     @Property({ type: 'boolean', default: false })
     banned!: boolean
   
     @Property({ fieldName: 'banReason', nullable: true })
     banReason: string | null = null
   
     @Property({ fieldName: 'banExpires', nullable: true })
     banExpires: Date | null = null
   
     // ... your existing timestamps and relations
   }

   About admin fields

   • role: Stores the user’s role (e.g., ‘user’, ‘admin’). The plugin automatically assigns the defaultRole on user creation.
   • banned: Boolean flag indicating if the user is banned from the application.
   • banReason: Optional text explaining why the user was banned.
   • banExpires: Optional date when the ban will be automatically lifted.

   Update the Session entity for impersonation

   The Admin plugin also adds an impersonatedBy field to track when an admin is impersonating another user:

   apps/api/src/modules/auth/auth.entity.ts

   @Entity({ tableName: 'session' })
   export class Session {
     // ... your existing properties
   
     @Property({ nullable: true })
     impersonatedBy!: string | null
   
     // ... your existing properties
   }

   About impersonation

   The impersonatedBy field stores the admin user ID when an admin is impersonating another user. This enables audit trails and helps distinguish between genuine user actions and admin actions performed on behalf of users.

   
   

3. Update the database

   Now that you have updated the entities, you need to update your database to add the new columns.

   Depending on your project stage, you can either recreate your database from scratch if you’re in development without important data, or use the migration system to preserve existing data.

   Need help with database updates?

   For detailed instructions on database migrations and schema updates, check out the Database Migrations explanation.

   
   

4. Use admin features

   Now that everything is configured on the API side, you can use admin-related methods from your services.

   Usage examples:

   import { Injectable } from '@nestjs/common'
   import { EntityManager } from '@mikro-orm/postgresql'
   import { User } from './auth.entity'
   
   @Injectable()
   export class UsersService {
     constructor(private readonly em: EntityManager) {}
   
     async ban(id: string, data: BanUserDto): Promise<void> {
       const user = await this.em.findOne(User, { id })
   
       if (!user) {
         throw new NotFoundException('User not found')
       }
   
       this.em.assign(user, {
         banned: true,
         banReason: data.banReason,
         banExpires: data.banExpires,
       })
   
       await this.em.flush()
     }
   
     async unban(id: string): Promise<void> {
       const user = await this.em.findOne(User, { id })
   
       if (!user) {
         throw new NotFoundException('User not found')
       }
   
       this.em.assign(user, {
         banned: false,
         banReason: null,
         banExpires: null,
       })
   
       await this.em.flush()
     }
   }

   Tip

   All available routes and methods are documented in the official Better Auth - Admin documentation.

   
   

The Admin plugin is now configured and operational. You can manage user roles, ban/unban users, and impersonate users via the Better Auth client.

Going further

NestJS Decorators & Guards

With @thallesp/nestjs-better-auth, prefer the built-in @Roles() decorator (admin plugin user.role) instead of forking AuthGuard.

Protect admin routes:

import { Controller, Get, Post, Body, Param } from '@nestjs/common'
import { Roles, Session } from '@thallesp/nestjs-better-auth'
import { LoggedInBetterAuthSession } from '../../modules/auth/auth.config'

@Controller('admin')
export class AdminController {
  @Get('users')
  @Roles(['admin'])
  async listUsers(@Session() session: LoggedInBetterAuthSession) {
    // Only users with role "admin" can access this endpoint
    return this.userService.findAll()
  }

  @Post('users/:id/ban')
  @Roles(['admin'])
  async banUser(@Param('id') userId: string, @Body() dto: BanUserDto) {
    return this.userService.ban(userId, dto)
  }
}

For organization-scoped roles, use @OrgRoles() / @RequireActiveOrg() from the same package (see the organizations addon).

You can still call Better Auth admin APIs via the injectable AuthService from @thallesp/nestjs-better-auth (authService.api / authService.instance).

Frontend admin UI examples

Here are some common patterns for building admin interfaces:

Admin check:

import { useAuth } from '@/lib/auth'

export function AdminPanel() {
  const { user } = useAuth()

  if (user?.role !== 'admin') {
    return <div>Access denied</div>
  }

  return (
    <div>
      <h1>Admin Panel</h1>
      {/* Admin features */}
    </div>
  )
}