API Reference
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._idasuserId). - 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. |
{baseUrl}/api/{apiVersion}/client/moderation/users/:userId/banAuthentication
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.
{
"banned": true
}Unban
Clear the ban. Success data.isBanned becomes false.
{
"banned": false
}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).
{
"success": true,
"message": "User banned successfully",
"data": {
"_id": "6a589b96cfa34ab66e35b2ab",
"name": "Bad Actor",
"email": "badactor@example.com",
"isActive": true,
"mutedUntil": "2026-07-16T09:03:29.501Z",
"isBanned": true
},
"error": null
}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
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 403 Forbidden — Tenant admin required
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}HTTP 404 Not Found — User missing
{
"success": false,
"message": "Entity not found",
"data": null,
"error": "Entity not found"
}| 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_deletedordismissed) 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.