Revoke User Session API endpoint and parameters
POST /admin/revoke-user-session. Required parameter: sessionToken (string). Revokes a specific session for a user.
admin & permissions
30 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Revoke All User Sessions API endpoint and parameters
POST /admin/revoke-user-sessions. Required parameter: userId (string). Revokes all sessions for a user.
Admin plugin user requirements
Before performing any admin operations, a user must be authenticated with an admin account. An admin is any user assigned the admin role or any user whose ID is included in the adminUserIds option.
Create User API endpoint and parameters
POST /admin/create-user. Parameters: email (string, required), password (string, required), name (string, required), role (string or string array, optional, defaults to 'user'), data (Record<string, any>, optional for extra custom fields).
List Users API endpoint and parameters
GET /admin/list-users. Optional parameters: searchValue (string), searchField ('email' or 'name', defaults to email), searchOperator ('contains', 'starts_with', or 'ends_with'), limit (number or string, defaults to 100), offset (number or string), sortBy (string), sortDirection ('asc' or 'desc'), filterField (string), filterValue (string, number, boolean, or array), filterOperator ('eq', 'ne', 'lt', 'lte', 'gt', 'gte', 'in', 'not_in', 'contains', 'starts_with', 'ends_with'). Returns object with users array, total count, limit, and offset.
Get User API endpoint and parameters
GET /admin/get-user. Required parameter: id (string). Returns object with data (User object or null) and error object containing message, status, statusText, and code on failure.
Set User Role API endpoint and parameters
POST /admin/set-role. Required parameter: role (string or string array). Optional parameter: userId (string).
Set User Password API endpoint and parameters
POST /admin/set-user-password. Required parameters: newPassword (string) and userId (string). A credential account is created if the user doesn't already have one.
Update User API endpoint and parameters
POST /admin/update-user. Required parameters: userId (string) and data (Record<string, any>).
Ban User API endpoint and parameters
POST /admin/ban-user. Required parameter: userId (string). Optional parameters: banReason (string), banExpiresIn (number in seconds, if not provided ban never expires). Banning prevents the user from signing in and revokes all existing sessions.
Unban User API endpoint and parameters
POST /admin/unban-user. Required parameter: userId (string). Removes the ban, allowing the user to sign in again.
List User Sessions API endpoint and parameters
POST /admin/list-user-sessions. Required parameter: userId (string). Lists all sessions for a user.
Impersonate User API endpoint and parameters
POST /admin/impersonate-user. Required parameter: userId (string). Creates a session that mimics the specified user. The session remains active until the browser session ends or reaches 1 hour (configurable via impersonationSessionDuration option). By default, admins cannot impersonate other admin users; grant the 'impersonate-admins' permission to allow this.
Stop Impersonating API endpoint
POST /admin/stop-impersonating. No parameters. Stops impersonating a user and continues with the admin account.
Remove User API endpoint and parameters
POST /admin/remove-user. Required parameter: userId (string). Hard deletes a user from the database.
Default admin plugin roles
By default, two roles exist: admin (has full control over other users) and user (has no control over other users). A user can have multiple roles, stored as comma-separated strings.
Default admin plugin permissions
Two resource types with default permissions: user resource has permissions 'create', 'list', 'set-role', 'ban', 'impersonate', 'impersonate-admins', 'delete', 'set-password', 'set-email', 'get', 'update'. session resource has permissions 'list', 'revoke', 'delete'. Admin role has full control; user role has no control.
Create access control with createAccessControl
Import createAccessControl from 'better-auth/plugins/access' (not from 'better-auth/plugins' to keep bundle size small). Use as const on the statement object so TypeScript can infer types correctly. The statement object should have resource names as keys and arrays of actions as values.
Create custom roles with ac.newRole
After creating an access controller with createAccessControl, use ac.newRole() to define custom roles. Pass an object where keys are resource names and values are arrays of actions. Each role gets exactly the permissions specified.
Merge custom roles with default admin permissions
When creating custom roles that override predefined roles, import defaultStatements and adminAc from 'better-auth/plugins/admin/access' and merge them with custom statements: spread defaultStatements in the statement object and spread adminAc.statements in the role definition.
Pass roles to admin plugin on server
Pass the access controller (ac) and roles object to adminPlugin() in betterAuth config: adminPlugin({ ac, roles: { admin, user, myCustomRole } }).
Pass roles to admin plugin on client
Pass the access controller (ac) and roles object to adminClient() in createAuthClient: adminClient({ ac, roles: { admin, user, myCustomRole } }).
Has Permission API endpoint and parameters
POST /admin/has-permission. Optional parameters: userId (string), role (string, server-only), permission (Record<string, string[]>, use this or permissions), permissions (Record<string, string[]>, use this or permission). Checks if a user or role has specified permissions.
Check role permission client-side
Use authClient.admin.checkRolePermission() to verify if a role has specific permissions. This is a synchronous function that does not check the current user's permissions directly, only what permissions are assigned to a specified role. No await needed.
Email enumeration protection with admin plugin
If using email enumeration protection (requireEmailVerification or autoSignIn: false), configure customSyntheticUser in emailAndPassword config to include admin plugin fields in the fake sign-up response: role, banned, banReason, and banExpires.
Admin plugin pagination example
Example of paginating listUsers results: const users = await authClient.admin.listUsers({ query: { limit: 10, offset: (currentPage - 1) * 10 } }); then calculate totalPages with Math.ceil(users.total / 10).
Has Permission client-side example
Example of checking permissions with hasPermission: const canCreateProject = await authClient.admin.hasPermission({ permissions: { project: ['create'] } }); Can check multiple resources: const result = await authClient.admin.hasPermission({ permissions: { project: ['create'], sale: ['create'] } });
Check role permission example
Example of checking role permissions client-side: const canCreateProject = authClient.admin.checkRolePermission({ permissions: { user: ['delete'] }, role: 'admin' }); Can check multiple resources: const result = authClient.admin.checkRolePermission({ permissions: { user: ['delete'], session: ['revoke'] }, role: 'admin' });
Impersonate admins permission grant
To allow admins to impersonate other admin users, grant the 'impersonate-admins' permission to a role: const superAdmin = ac.newRole({ ...adminAc.statements, user: ['impersonate-admins', ...adminAc.statements.user] });
Server-side permission check example
Example of checking permissions server-side using auth.api.userHasPermission: await auth.api.userHasPermission({ body: { userId: 'id', permissions: { project: ['create'] } } }); Or using role: await auth.api.userHasPermission({ body: { role: 'admin', permissions: { project: ['create'] } } }); Can check multiple: await auth.api.userHasPermission({ body: { role: 'admin', permissions: { project: ['create'], sale: ['create'] } } });