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.
email	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.

GET{baseUrl}/api/{apiVersion}/user/:userId

Authentication: 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 `userId`equals 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.

json

1{2  "success": true,3  "message": "User fetched successfully",4  "data": {5    "_id": "694b7ab37f8f05a7ac678b6b",6    "name": "Gomez",7    "email": "gomez@example.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z",12    "refreshToken": <refresh_token>13  },14  "error": null15}

Success - Different login user id and user id

You requested another user's id (contact profile). refreshToken is not included.

json

1{2  "success": true,3  "message": "User fetched successfully",4  "data": {5    "_id": "694b...8b6b",6    "name": "Gomez",7    "email": "gomez@example.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z"12  },13  "error": null14}

Common Errors

Get fails when the token is missing, the user does not exist, or tenant headers are wrong.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "User not found",4  "data": null,5  "error": "User not found"6}

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 userId is a 24-character ObjectId before calling the API.
Cache contact profiles briefly in the chat client; refetch when opening the profile sheet.
Treat refreshToken as 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.

Overview

Fetch a single chat user by their userId - for contact profiles, header chips, and participant details inside the messaging UI.

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.

Response Data

The data object typically includes:

Field	Description
_id	Unique user id (same as the path `userId`).
name	Display name.
email	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.

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

Tenant (client) id. Required when is-tenant=true.

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 `userId`equals 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.

json

1{2  "success": true,3  "message": "User fetched successfully",4  "data": {5    "_id": "694b7ab37f8f05a7ac678b6b",6    "name": "Gomez",7    "email": "gomez@example.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z",12    "refreshToken": <refresh_token>13  },14  "error": null15}

Success - Different login user id and user id

You requested another user's id (contact profile). refreshToken is not included.

json

1{2  "success": true,3  "message": "User fetched successfully",4  "data": {5    "_id": "694b...8b6b",6    "name": "Gomez",7    "email": "gomez@example.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z"12  },13  "error": null14}

Common Errors

Get fails when the token is missing, the user does not exist, or tenant headers are wrong.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "User not found",4  "data": null,5  "error": "User not found"6}

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 userId is a 24-character ObjectId before calling the API.
Cache contact profiles briefly in the chat client; refetch when opening the profile sheet.
Treat refreshToken as 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.