Ban user
Users
Ban user
Ban a user, record the reason, and revoke all of their active refresh tokens. SUPER or MODERATOR only.
POST
Ban user
Overview
Bans a user account. The operation:- Sets
users.status = BANNED,users.bannedAt = now,users.bannedReason = reason. - Revokes every active refresh token the user holds — they are forced to re-login on all devices and will then hit the disabled-account gate.
bannedAt/bannedReason are not overwritten).
Authentication
Bearer <accessToken> with scope: 'admin' required (requireAdmin).
Path parameters
| Name | Type | Required | Notes | Example |
|---|---|---|---|---|
id | string | yes | User ObjectId, 1..64 chars. | 66400a8f1c2b4d5e6f7a8b01 |
Query parameters
None.Request body
| Field | Type | Required | Notes | Example |
|---|---|---|---|---|
reason | string | yes | 1..500 chars. Recorded on the user row and surfaced in the audit log. | Repeated harassment reports |
Example payload
Response — 200 OK
Returns the updated user summary object.
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | reason missing, empty, or over 500 chars. |
| 401 | UNAUTHENTICATED | Missing, malformed, expired, or non-admin-scope token. |
| 403 | FORBIDDEN | Caller is a FINANCE admin (read-only on the user surface). |
| 404 | NOT_FOUND | No user with that id. |
Example error — 403 FORBIDDEN
Side effects
usersrow updated (status,bannedAt,bannedReason).- All of the user’s
refresh_tokensrows revoked. - An audit-log row is written (admin id, target user id, action
users.ban).
See also
- Unban user — reverse the ban.
- Admin user search — find the user to ban.
curl
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Users → Ban.