API Reference
Get User Details
Overview
Fetch a single chat user by their userId — for contact profiles, header chips, and participant details inside the messaging UI.
Returns core identity fields, role, and active status. When the path userId matches the signed-in user (same login user id), the payload also includes refreshToken. When you fetch someone else, that field is omitted.
When to use this endpoint?
Use Get User Details when:
- Opening a contact profile sheet from a conversation or people picker.
- Showing name / email on a chat header or message author popover.
- Hydrating a group participant chip with a full user record.
- Confirming a user still exists before starting a DM.
Part of the Chat User APIs (not Platform → Users). If path userId matches the logged-in user, refreshToken is included. For shell avatar/name without that token field, you can also use Get My Profile.
Response Data
The data object typically includes:
| Field | Description |
|---|---|
| _id | Unique user id (same as the path userId). |
| name | Display name. |
| User email address. | |
| isActive | Whether the account is active in the tenant. |
| role | Tenant role slug (for example user). |
| createdAt / updatedAt | ISO timestamps for when the record was created and last updated. |
| refreshToken | Present only when the logged-in user id equals the path userId (fetching yourself). Omitted for other users. |
{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)
Both cases return HTTP 200. The shape of data depends on whether the path userId is the same as the logged-in user from the Access Token.
| Case | Condition | Includes refreshToken? |
|---|---|---|
| Same login user id and user id | Path userIdequals the signed-in user's id | Yes — data.refreshToken is returned |
| Different login user id and user id | Path userId is another chat user | No — profile fields only (no refreshToken) |
Success — Same login user id and user id
You requested your own id. The response includes refreshToken along with the profile fields.
{
"success": true,
"message": "User fetched successfully",
"data": {
"_id": "694b7ab37f8f05a7ac678b6b",
"name": "Gomez",
"email": "gomez@example.com",
"isActive": true,
"role": "user",
"createdAt": "2025-12-24T05:31:31.606Z",
"updatedAt": "2025-12-24T05:31:31.723Z",
"refreshToken": <refresh_token>
},
"error": null
}Success — Different login user id and user id
You requested another user's id (contact profile). refreshToken is not included.
{
"success": true,
"message": "User fetched successfully",
"data": {
"_id": "694b...8b6b",
"name": "Gomez",
"email": "gomez@example.com",
"isActive": true,
"role": "user",
"createdAt": "2025-12-24T05:31:31.606Z",
"updatedAt": "2025-12-24T05:31:31.723Z"
},
"error": null
}Common Errors
Get fails when the token is missing, the user does not exist, or tenant headers are wrong.
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 in this tenant. |
| 500 Internal Server Error | An unexpected error occurred while fetching the user. |
Best Practices
- Validate
userIdis a 24-character ObjectId before calling the API. - Cache contact profiles briefly in the chat client; refetch when opening the profile sheet.
- Treat
refreshTokenas sensitive — store it only when present (self-fetch). Never expect it on contact profiles. - Prefer Get My Profile for the signed-in shell avatar/name; use this endpoint when you need self
refreshTokenor another user's public profile. - Always send tenant headers with the chat user Bearer token over HTTPS.
Contact profile ready
Render the contact in your chat profile sheet. From there, start a DM, add them to a group, or use Block / Unblock for safety actions.