Ban / Unban User

Overview

Ban or unban a tenant chat user from Platform Moderation. A banned user is blocked from participating in chat according to your product rules, independent of any temporary mute.

Send banned: true to ban, or banned: falseto unban. On success, the API returns the user's updated moderation state, including isBanned.

When to use this endpoint?

Use Ban / Unban User when:

A moderator permanently (or until unban) blocks a report sender for serious policy violations.
Restoring access by unbanning a user (banned: false).
Acting from Platform → Moderation after reviewing List Reports (use messageSender._id as userId).
Preferring a lasting account action instead of (or after) a temporary Mute.

Part of the client Platform Moderation module. Ban and mute are independent - a user can be banned while still having a mutedUntil timestamp from a prior mute.

Request Fields

Field	Required	Description
banned	Required	`true` to ban the user; `false` to unban.

PATCH{baseUrl}/api/{apiVersion}/client/moderation/users/:userId/ban

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
Content-Type	application/json	Required when sending a JSON body.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Path Parameters

Parameter	Example	Description
userId	6a589b96cfa34ab66e35b2ab	The chat user to ban or unban (for example `messageSender._id` from List Reports).

Request Payload

Ban

Set isBanned to true on the user.

json

1{2  "banned": true3}

Unban

Clear the ban. Success data.isBanned becomes false.

json

1{2  "banned": false3}

Success Response (HTTP 200 OK)

Returns the updated user moderation fields. In this ban example, isBanned is true. Any existing mutedUntil is returned as-is (ban does not clear a mute).

json

1{2  "success": true,3  "message": "User banned successfully",4  "data": {5    "_id": "6a589b96cfa34ab66e35b2ab",6    "name": "Bad Actor",7    "email": "badactor@example.com",8    "isActive": true,9    "mutedUntil": "2026-07-16T09:03:29.501Z",10    "isBanned": true11  },12  "error": null13}

Response data fields

Field	Description
_id	User id (same as path).
name / email	User display identity.
isActive	Account active flag (separate from ban state).
isBanned	`true` when banned; `false` after unban.
mutedUntil	Existing mute expiry if present - not cleared by ban/unban.

Common Errors

Ban fails when auth is invalid, the user id is missing, or banned is invalid.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

Code	Reason
400 Bad Request	Missing or non-boolean `banned` field.
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Moderation.
404 Not Found	No user exists for the given `userId`.
500 Internal Server Error	An unexpected error occurred while updating ban state.

Best Practices

Confirm ban in the UI - it is a stronger action than mute.
After ban or unban, refetch List Reports so sender badges refresh.
You may still Resolve the related report (message_deleted or dismissed) in a separate step.
Use mute for temporary cooldowns; reserve ban for lasting blocks.
Check Audit Logs if you need a history of ban / unban actions.

Ban state updated

Bind data.isBanned in the moderation UI. Continue with Resolve Reports if the queue item is still pending, or review Audit Logs for the action trail.

Overview

Ban or unban a tenant chat user from Platform Moderation. A banned user is blocked from participating in chat according to your product rules, independent of any temporary mute.

Send banned: true to ban, or banned: falseto unban. On success, the API returns the user's updated moderation state, including isBanned.

When to use this endpoint?

Use Ban / Unban User when:

A moderator permanently (or until unban) blocks a report sender for serious policy violations.
Restoring access by unbanning a user (banned: false).
Acting from Platform → Moderation after reviewing List Reports (use messageSender._id as userId).
Preferring a lasting account action instead of (or after) a temporary Mute.

Part of the client Platform Moderation module. Ban and mute are independent - a user can be banned while still having a mutedUntil timestamp from a prior mute.

Field

Required

Description

banned

Required

true to ban the user; false to unban.

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
Content-Type	application/json	Required when sending a JSON body.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Parameter

Example

Description

userId

6a589b96cfa34ab66e35b2ab

The chat user to ban or unban (for example messageSender._id from List Reports).

Success Response (HTTP 200 OK)

Returns the updated user moderation fields. In this ban example, isBanned is true. Any existing mutedUntil is returned as-is (ban does not clear a mute).

json

1{2  "success": true,3  "message": "User banned successfully",4  "data": {5    "_id": "6a589b96cfa34ab66e35b2ab",6    "name": "Bad Actor",7    "email": "badactor@example.com",8    "isActive": true,9    "mutedUntil": "2026-07-16T09:03:29.501Z",10    "isBanned": true11  },12  "error": null13}

Response data fields

Field	Description
_id	User id (same as path).
name / email	User display identity.
isActive	Account active flag (separate from ban state).
isBanned	`true` when banned; `false` after unban.
mutedUntil	Existing mute expiry if present - not cleared by ban/unban.

Common Errors

Ban fails when auth is invalid, the user id is missing, or banned is invalid.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

Code	Reason
400 Bad Request	Missing or non-boolean `banned` field.
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Moderation.
404 Not Found	No user exists for the given `userId`.
500 Internal Server Error	An unexpected error occurred while updating ban state.

Best Practices

Confirm ban in the UI - it is a stronger action than mute.
After ban or unban, refetch List Reports so sender badges refresh.
You may still Resolve the related report (message_deleted or dismissed) in a separate step.
Use mute for temporary cooldowns; reserve ban for lasting blocks.
Check Audit Logs if you need a history of ban / unban actions.