API Reference
Delete User
Overview
Permanently remove a single tenant user by userId.
On success, the API reports how many users and related memberships were deleted. Use this for one-off removals from an admin detail view; prefer Bulk Delete Users when removing many accounts at once.
When to use this endpoint?
Use Delete User when:
- An admin removes one user from the tenant workspace.
- You need to clean up a test or inactive account by its
_id. - A confirmation dialog already collected a single target user id.
- You want a deletion summary that includes related membership cleanup counts.
DELETE
{baseUrl}/api/{apiVersion}/client/users/:userIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| userId | string | User _id (24-char Mongo ObjectId). |
Success Response (HTTP 200 OK)
When deletion succeeds, the API returns counts for users and related members removed.
json
{
"success": true,
"message": "User deleted successfully",
"data": {
"usersDeleted": 1,
"membersDeleted": 4
},
"error": null
}Common Errors
HTTP 200 OK means the user was deleted. Deletion fails when the user does not exist or the request is not authenticated.
HTTP 404 Not Found — Not found
json
{
"success": false,
"message": "User not found",
"data": null,
"error": "User not found"
}| Code | Reason |
|---|---|
| 400 Bad Request | Required headers are missing or userId is invalid. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | User not found for the given userId. |
| 500 Internal Server Error | An unexpected error occurred while deleting the user. |
Best Practices
- Confirm the target user in the UI before calling delete — this action is permanent.
- Handle 404 Not Found gracefully if the user was already removed.
- Refresh List Users after a successful delete so the directory stays accurate.
- Use Bulk Delete Users instead when removing more than one account in a single operation.
User removed
After a successful delete, return to List Users and verify the account no longer appears in the tenant directory.