API Reference
Delete User
Overview
Permanently remove a chat user by their userId — for example account deletion or cleaning up a messaging identity from the chat app.
On success, the API returns the deleted user so you can clear local chat state (threads, caches, people picker). This is not Platform panel bulk/user admin delete (Platform → Users).
When to use this endpoint?
Use Delete User when:
- The chat participant deletes their messaging account.
- You need to remove a test or obsolete chat identity from the tenant.
- Hard delete is required — not just hiding someone from chats.
Deletion is irreversible. Prefer Block / Unblock when a participant only needs to stop messaging someone without removing either account.
{baseUrl}/api/{apiVersion}/user/:userIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Chat user Access Token (Bearer) for the signed-in messaging participant. |
| 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 | 694b7ab37f8f05a7ac678b6b | The target user's _id (24-char Mongo ObjectId). |
Success Response (HTTP 200 OK)
On success, the API returns the deleted user snapshot.
{
"success": true,
"message": "User deleted successfully",
"data": {
"_id": "694b7ab37f8f05a7ac678b6b",
"name": "test 2 user",
"email": "test2@hgmail.com",
"isActive": true,
"role": "user",
"createdAt": "2025-12-24T05:31:31.606Z",
"updatedAt": "2025-12-24T05:31:31.723Z",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY5NGI3YWIzN2Y4ZjA1YTdhYzY3OGI2YiIsImlhdCI6MTc2NjU1NDI5MSwiZXhwIjoxNzY3MTU5MDkxfQ.xArw6kNaz9cc3nW2IXh6tgj7GyIJXXa2i1A6r1Oi8Mw"
},
"error": null
}Common Errors
Delete fails when the token is missing or the user does not exist.
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 404 Not Found — User missing
{
"success": false,
"message": "User not found",
"data": null,
"error": "User not found"
}| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | No user exists for the given userId. |
| 500 Internal Server Error | An unexpected error occurred while deleting the user. |
Best Practices
- Confirm with a destructive step in chat settings before calling delete.
- Clear local conversations, draft messages, and people-picker cache for the deleted
_id. - Prefer block when the goal is only to stop messaging a peer; use delete only when the chat account itself must be removed.
- Always send tenant headers with the chat user Bearer token over HTTPS.
Chat user deleted
Sign the participant out of chat if they deleted themselves, or remove them from pickers and threads using the returned _id.