Disable a user who violates application rules
Account enforcement
Clerk · Module
users.banUser
Use banUser() in Clerk's JavaScript Backend SDK to ban a user by ID. The operation revokes the user's sessions and blocks future sign-ins.
How it works
Call clerkClient.users.banUser() with the target user's ID from a trusted server environment. Clerk marks the user as banned, revokes every active session, prevents future sign-ins, and returns the updated User object.
Syntax
function banUser(userId: string): Promise<User>Parameters
| Name | Type | Description |
|---|---|---|
userId | string | The ID of the user to ban. |
Returns
Promise<User> resolving to the banned user.
Key points
- The method changes the targeted Clerk user to a banned state.
- Existing sessions are revoked as part of the ban.
- A banned user cannot authenticate again until the ban is removed.
- The signature takes a string user ID and asynchronously returns a User.
- Pass the Clerk user identifier for the account that should be banned.
- The documented invocation uses the Clerk client, the users namespace, and await.
Common mistakes
- The exact import and setup for
clerkClientdepend on the Clerk server SDK in use; follow that SDK's access pattern. - This helper is a Backend API wrapper, so it belongs in backend code rather than browser-side client code.
Example: Ban a user
import { clerkClient } from '@clerk/express'
const userId = 'user_123'
const user = await clerkClient.users.banUser(userId)
console.log(user.banned)Calls Clerk from a server-side application and prints the returned user's banned status.
When to use it
Immediately invalidate access after detecting a compromised account
Security response
Apply a user ban from an administrative backend
Moderation workflow
Interview questions
QWhat does banUser() do?
banUser(userId) marks the specified Clerk user as banned and returns a Promise<User>. Banning revokes all of that user's sessions and prevents the user from signing in again.
Follow-up: What endpoint does the helper wrap? It wraps the Backend API POST/users/{user_id}/ban.
QWhat are the parameter and return value?
The method accepts one parameter: userId, a string containing the ID of the user to ban. The returned promise resolves to the updated User object.
Follow-up: How would you remove the restriction? Use Clerk's corresponding unbanUser() method.
QHow is the method invoked in an application?
Use the server-side clerkClient and call clerkClient.users.banUser(userId). The SDK setup and import vary by the Clerk SDK used, so the application must follow that SDK's server configuration.
Follow-up: Why should the operation not run in client code? It is a privileged Backend API operation and should be performed from a trusted server environment.
Related
unbanUser()UserclerkClientBackend API