API Reference
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.
{baseUrl}/api/{apiVersion}/user/login/client-userAuthentication
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. |
| 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). |
{
"name": "Will Smith",
"email": "will.smith@example.com",
"role": "user",
"metadata": {
"department": "sales"
}
}Success Response (HTTP 201 Created)
On success, data is the new (or resolved) user id string.
{
"success": true,
"message": "User created successfully",
"data": "694b76ab3d833c4b8a3f57d8",
"error": null
}Common Errors
Login / create fails when tenant headers are invalid or permissions block user creation.
HTTP 400 Bad Request — Invalid tenant
{
"success": false,
"message": "Invalid tenant ID or isTenant header",
"data": null,
"error": null
}HTTP 403 Forbidden — Insufficient permissions
{
"success": false,
"message": "Access denied: insufficient permissions",
"data": null,
"error": null
}HTTP 403 Forbidden — Error: banned by workspace admin
{
"success": false,
"message": "Your account has been banned by the workspace admin",
"data": null,
"error": null
}| 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
userfor typical messaging participants unless your product needs custom roles. - Keep metadata keys stable so chat people-picker filters stay reliable.
- Always send
is-tenantandx-client-idover 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.