Admin

The Admin plugin provides a set of administrative functions for user management in your application. It allows administrators to perform various operations such as creating users, managing user roles, banning/unbanning users, impersonating users, and more.

Installation

import { betterAuth } from "better-auth"
import { admin } from "better-auth/plugins"
 
export const auth = betterAuth({
    // ... other config options
    plugins: [
        admin() 
    ]
})

npx @better-auth/cli migrate

import { createAuthClient } from "better-auth/client"
import { adminClient } from "better-auth/client/plugins"
 
const authClient = createAuthClient({
    plugins: [
        adminClient()
    ]
})

Usage

Before performing any admin operations, the user must be authenticated with an admin account. An admin is any user assigned the admin role. For the first admin user, you'll need to manually assign the admin role to their account in your database.

Create User

Allows an admin to create a new user.

const newUser = await authClient.admin.createUser({
  name: "Test User",
  email: "[email protected]",
  password: "password123",
  role: "user",
  data: {
    // any additional on the user table including plugin fields and custom fields
    customField: "customValue"
  }
});

List Users

Allows an admin to list all users in the database.

const users = await authClient.admin.listUsers({
    query: {
        limit: 10,
    }
});

By default, 100 users are returned. You can adjust the limit and offset using the following query parameters:

• search: The search query to apply to the users. It can be an object with the following properties:
  • field: The field to search on, which can be email or name.
  • operator: The operator to use for the search. It can be contains, starts_with, or ends_with.
  • value: The value to search for.
• limit: The number of users to return.
• offset: The number of users to skip.
• sortBy: The field to sort the users by.
• sortDirection: The direction to sort the users by. Defaults to asc.
• filter: The filter to apply to the users. It can be an array of objects.

const users = await authClient.admin.listUsers({
    query: {
        searchField: "email",
        searchOperator: "contains",
        searchValue: "@example.com",
        limit: 10,
        offset: 0,
        sortBy: "createdAt",
        sortDirection: "desc"
        filterField: "role",
        filterOperator: "eq",
        filterValue: "admin"
    }
});

Set User Role

Changes the role of a user.

const updatedUser = await authClient.admin.setRole({
  userId: "user_id_here",
  role: "admin"
});

Ban User

Bans a user, preventing them from signing in and revokes all of their existing sessions.

const bannedUser = await authClient.admin.banUser({
  userId: "user_id_here",
  banReason: "Spamming", // Optional (if not provided, the default ban reason will be used - No reason)
  banExpiresIn: 60 * 60 * 24 * 7 // Optional (if not provided, the ban will never expire)
});

Unban User

Removes the ban from a user, allowing them to sign in again.

const unbannedUser = await authClient.admin.unbanUser({
  userId: "user_id_here"
});

List User Sessions

Lists all sessions for a user.

const sessions = await authClient.admin.listUserSessions({
  userId: "user_id_here"
});

Revoke User Session

Revokes a specific session for a user.

const revokedSession = await authClient.admin.revokeUserSession({
 sessionToken: "session_token_here"
});

Revoke All Sessions for a User

Revokes all sessions for a user.

const revokedSessions = await authClient.admin.revokeUserSessions({
  userId: "user_id_here"
});

Impersonate User

This feature allows an admin to create a session that mimics the specified user. The session will remain active until either the browser session ends or it reaches 1 hour. You can change this duration by setting the impersonationSessionDuration option.

const impersonatedSession = await authClient.admin.impersonateUser({
  userId: "user_id_here"
});

Stop Impersonating User

To stop impersonating a user and continue with the admin account, you can use stopImpersonating

await authClient.admin.stopImpersonating();

Remove User

Hard deletes a user from the database.

const deletedUser = await authClient.admin.removeUser({
  userId: "user_id_here"
});

Schema

This plugin adds the following fields to the user table:

And adds one field in the session table:

Options

Default Role

The default role for a user. Defaults to user.

admin({
    defaultRole: "regular"
})

you can pass false to disable assigning default role

admin({
    defaultRole: false //pass false to disable default role assignment
})

Admin role

You can specify what role should be consider admin. Default to admin

admin({
    adminRole: ["admin", "superAdmin"]
})

impersonationSessionDuration

The duration of the impersonation session in seconds. Defaults to 1 hour.

admin({
    impersonationSessionDuration: 60 * 60 * 24 // 1 day
})

Default Ban Reason

The default ban reason for a user created by the admin. Defaults to No reason.

admin({
    defaultBanReason: "Spamming"
})

Default Ban Expires In

The default ban expires in for a user created by the admin in seconds. Defaults to undefined (meaning the ban never expires).

admin({
    defaultBanExpiresIn: 60 * 60 * 24 // 1 day
})