API Reference

Register Client

Overview

Create a new client (tenant) account to start using the RealtimeX platform. This is typically the first step when integrating RealtimeX into your application.

Once the registration is successful, the API returns:

A Client ID that identifies your tenant workspace.
An Access Token used to authenticate API requests.
A Refresh Token used to obtain new access tokens when the current one expires.

What happens during registration?

Your application sends the client details to the registration endpoint.
RealtimeX creates a dedicated tenant workspace for the client.
Authentication tokens are generated and returned.
The Client ID is stored for all future tenant-scoped requests.

POST{baseUrl}/api/{apiVersion}/auth/jwt/client/register

Authentication

Not required

Tenant-scoped

No (root DB)

Request Headers

Header	Value	Description
Content-Type	application/json	Specifies the content type of the request body.
is-tenant	false	Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

Request Payload

json

{
  "name": "client pro 1",
  "email": "cilentpro1@yoppmail.com",
  "slug": "client-pro-1",
  "password": "test@123",
  "metadata": {
    "plan": "pro"
  }
}

Parameter	Type	Required	Description
name	string		The name of the client.
email	string		The email of the client.
slug	string		The slug of the client.
password	string		The password of the client.
metadata	object	Optional	The metadata of the client.

Success Response (HTTP 201 Created)

json

{
  "success": true,
  "message": "Client registered successfully",
  "data": {
    "client": {
      "name": "client pro 1",
      "email": "cilentpro1@yoopmail.com",
      "slug": "client-pro-1",
      "password": "$2b$10$0CfdKGTQJSnxHEeLAcSJi.YeoxbqIgj6tmkQVmF6qvaW5clwjH58K",
      "isActive": true,
      "_id": "699fe1377846dcfb775c645c",
      "createdAt": "2026-02-26T05:59:19.339Z",
      "updatedAt": "2026-02-26T05:59:19.339Z",
      "__v": 0
    },
    "accessToken": "<access-token>",
    "refreshToken": "<refresh-token>"
  },
  "error": null
}

After Registration

Store these values securely

You’ll use them for all subsequent API requests.

Access Token

Required

Include in the Authorization header.

Refresh Token

Required

Generate a new access token when needed.

Client ID

Tenant APIs

Send with x-client-id for tenant-scoped endpoints.

Next Request Example

After registration, authenticate subsequent tenant-scoped requests like this:

http

GET /api/v1/user/list HTTP/1.1
Authorization: Bearer <access_token>
is-tenant: true
x-client-id: <client_id>

Common Errors

Code	Meaning	Reason
400 Bad Request	Invalid or missing fields	The request body is incomplete or contains invalid data.
409 Conflict	Client already exists	A client account with the same email already exists.
500 Internal Server Error	Unexpected error	An unexpected error occurred on the server.

You’re ready to continue

Once registration is complete, proceed to Auth → Login Client or start calling protected tenant APIs using the returned credentials.

Header

Value

Description

Content-Type

application/json

Specifies the content type of the request body.

is-tenant

false

Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

Parameter

Type

Required

Description

name

string

The name of the client.

string

The email of the client.

slug

string

The slug of the client.

password

string

The password of the client.

metadata

object

Optional

The metadata of the client.

{ "success": true, "message": "Client registered successfully", "data": { "client": { "name": "client pro 1", "email": "cilentpro1@yoopmail.com", "slug": "client-pro-1", "password": "$2b$10$0CfdKGTQJSnxHEeLAcSJi.YeoxbqIgj6tmkQVmF6qvaW5clwjH58K", "isActive": true, "_id": "699fe1377846dcfb775c645c", "createdAt": "2026-02-26T05:59:19.339Z", "updatedAt": "2026-02-26T05:59:19.339Z", "__v": 0 }, "accessToken": "<access-token>", "refreshToken": "<refresh-token>" }, "error": null }

Code

Meaning

Reason

400 Bad Request

Invalid or missing fields

The request body is incomplete or contains invalid data.

409 Conflict

Client already exists

A client account with the same email already exists.

500 Internal Server Error

Unexpected error

An unexpected error occurred on the server.