Login Client User

Overview

Sign a participant into your chat app by creating or resolving their chat user with name, email, and optional role or metadata. No Bearer token is required - tenant context comes from x-client-id.

On success, data is the chat user id. Use it for conversations, messages, profile, and other User endpoints in this section. This is not Platform client login (Auth → Login Client).

When to use this endpoint?

Use Login Client User when:

A visitor opens your embedded or standalone chat and needs a chat identity.
You onboard a messaging participant without the Platform register / password flow.
You need a stable user id before listing chats, opening a thread, or sending the first message.
You attach chat-side metadata (locale, device, department) at first login.

Part of the Chat User APIs. Always send valid tenant headers — an invalid x-client-id or is-tenant value is rejected.

POST{baseUrl}/api/{apiVersion}/user/login/client-user

Authentication: Not required
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. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Request Payload

Send identity fields for the chat participant. name and email are required; role and metadata are optional.

Field	Type	Required	Description
name	string	Required	Display name for the user.
email	string	Required	User email - used as a unique identity within the tenant.
role	string	Optional	Tenant role slug (for example `user`). Defaults apply when omitted.
metadata	object	Optional	Arbitrary key-value map for app-specific attributes (department, plan, external ids).

json

1{2  "name": "Will Smith",3  "email": "will.smith@example.com",4  "role": "user",5  "metadata": {6    "department": "sales"7  }8}

Success Response (HTTP 201 Created)

On success, data is the new (or resolved) user id string.

json

1{2  "success": true,3  "message": "User created successfully",4  "data": "694b76ab3d833c4b8a3f57d8",5  "error": null6}

Common Errors

HTTP 400 Bad Request - Invalid tenant

json

1{2  "success": false,3  "message": "Invalid tenant ID or isTenant header",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Insufficient permissions

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Error: banned by workspace admin

json

1{2  "success": false,3  "message": "Your account has been banned by the workspace admin",4  "data": null,5  "error": null6}

Code	Reason
400 Bad Request	Invalid tenant ID or `is-tenant` header, or missing required fields.
403 Forbidden	Access denied: insufficient permissions to create the user.
500 Internal Server Error	An unexpected error occurred while provisioning the user.

Workflow

1
Send chat identity
From your chat app, send the participant’s name, email, optional role, and optional metadata.
2
Chat user is ready
RealtimeX creates or resolves the chat user in the tenant DB and returns their user id.
3
Enter the chat session
Store the returned id and use it as the signed-in chat participant for conversations, messages, profile, and block flows.

Best Practices

Persist the returned chat user id in your chat session storage; do not re-create on every reload when the same email is already known.
Default role to user for typical messaging participants unless your product needs custom roles.
Keep metadata keys stable so chat people-picker filters stay reliable.
Always send is-tenant and x-client-id over HTTPS.

Chat user ready

Store the returned id, then load chats with Conversation / Messages APIs, or open Get My Profile to hydrate the chat header.

Overview

On success, data is the chat user id. Use it for conversations, messages, profile, and other User endpoints in this section. This is not Platform client login (Auth → Login Client).

When to use this endpoint?

Use Login Client User when:

A visitor opens your embedded or standalone chat and needs a chat identity.
You onboard a messaging participant without the Platform register / password flow.
You need a stable user id before listing chats, opening a thread, or sending the first message.
You attach chat-side metadata (locale, device, department) at first login.

Part of the Chat User APIs. Always send valid tenant headers — an invalid x-client-id or is-tenant value is rejected.

Header

Value

Description

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

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

Content-Type

application/json

JSON request body.

Request Payload

Send identity fields for the chat participant. name and email are required; role and metadata are optional.

Field	Type	Required	Description
name	string	Required	Display name for the user.
email	string	Required	User email - used as a unique identity within the tenant.
role	string	Optional	Tenant role slug (for example `user`). Defaults apply when omitted.
metadata	object	Optional	Arbitrary key-value map for app-specific attributes (department, plan, external ids).

json

1{2  "name": "Will Smith",3  "email": "will.smith@example.com",4  "role": "user",5  "metadata": {6    "department": "sales"7  }8}

Common Errors

HTTP 400 Bad Request - Invalid tenant

json

1{2  "success": false,3  "message": "Invalid tenant ID or isTenant header",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Insufficient permissions

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Error: banned by workspace admin

json

1{2  "success": false,3  "message": "Your account has been banned by the workspace admin",4  "data": null,5  "error": null6}

Code	Reason
400 Bad Request	Invalid tenant ID or `is-tenant` header, or missing required fields.
403 Forbidden	Access denied: insufficient permissions to create the user.
500 Internal Server Error	An unexpected error occurred while provisioning the user.

Workflow

1
Send chat identity
From your chat app, send the participant’s name, email, optional role, and optional metadata.
2
Chat user is ready
RealtimeX creates or resolves the chat user in the tenant DB and returns their user id.
3
Enter the chat session
Store the returned id and use it as the signed-in chat participant for conversations, messages, profile, and block flows.

Best Practices

Persist the returned chat user id in your chat session storage; do not re-create on every reload when the same email is already known.
Default role to user for typical messaging participants unless your product needs custom roles.
Keep metadata keys stable so chat people-picker filters stay reliable.
Always send is-tenant and x-client-id over HTTPS.

HTTP 400 Bad Request - Invalid tenant

HTTP 403 Forbidden - Insufficient permissions

HTTP 403 Forbidden - Error: banned by workspace admin

Send chat identity

Chat user is ready

Enter the chat session

Chat user ready

HTTP 400 Bad Request - Invalid tenant

HTTP 403 Forbidden - Insufficient permissions

HTTP 403 Forbidden - Error: banned by workspace admin

Send chat identity

Chat user is ready

Enter the chat session

Chat user ready