​
Admin Plugin Configuration

​
Overview

The Better Auth Admin Plugin provides platform-level administrative capabilities. In the Gremlin monorepo, it is used to manage global user roles (user, admin, superadmin) and perform administrative actions like banning or deleting users.

​
Configuration

The plugin is enabled during the betterAuth initialization in the DIContainer.

​
Location

backend/bun/apps/monolith/src/config/di-container.ts

​
Implementation

import { admin } from 'better-auth/plugins';

this.auth = betterAuth({
  // ... other config
  plugins: [
    admin(), // Default configuration
  ],
});
The default configuration enables:
  • Platform Roles: Core roles for system-wide permissions.
  • Admin APIs: Endpoints for managing users and roles.
  • Banning: Ability to suspend user access globally.

​
Core Features

​
1. Platform Roles

The plugin adds a role field to the users table.
RoleDescription
userDefault role for all new signups. Regular platform access.
adminCan perform administrative tasks (manage other users).
superadminHighest privilege level. Usually restricted to system owners.

​
2. Administrative Endpoints

The Bun backend exposes these endpoints via the Better Auth API:
  • POST /api/auth/admin/set-role: Change a user’s platform role.
  • POST /api/auth/admin/ban-user: Suspend a user.
  • POST /api/auth/admin/unban-user: Lift a suspension.
  • POST /api/auth/admin/delete-user: Permanently remove a user.

​
3. Middleware Integration

Platform roles are extracted in the jwt plugin and injected into the authentication token: 
jwt({
  jwt: {
    definePayload: async ({ user }) => {
      return {
        // ...
        role: (user as any).role ?? 'user', // Maps admin plugin role
        isActive: !(user as any).banned,    // Maps admin plugin banned status
      };
    }
  }
})

​
Usage Example

​
Promoting a User to Admin

To promote a user, a superadmin would call: 
curl -X POST http://localhost:3100/api/auth/admin/set-role \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SUPERADMIN_TOKEN>" \
  -d '{
    "userId": "user_id_here",
    "role": "admin"
  }'

​
Security Considerations

  • Strict Access: Only users with superadmin role can escalate other users to admin.
  • JWT Invalidation: Banning a user does not immediately invalidate their current JWT. The Go backend handles this by checking the isActive claim during the 5-minute cache TTL window, or by checking the database if the claim is missing.