​

Admin Plugin Configuration

​

Overview

​

Configuration

​

Location

​

Implementation

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

this.auth = betterAuth({
  // ... other config
  plugins: [
    admin(), // Default configuration
  ],
});

• 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

​

2. Administrative Endpoints

• 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

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

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.

​

Related Documents

• Authentication Architecture
• Role Assignment Guide
• Organization Plugin Configuration