Authentication

Follow these steps to authenticate your application and make protected API requests.

1. 1

   Register or Login Client

   Authenticate your client by calling either Register Client or Login Client. A successful response returns an Access Token and a Refresh Token.

2. 2

   Add Tenant Headers

   For tenant-scoped APIs, include the required tenant headers with every request.

   httpCopy

   is-tenant: true
   x-client-id: {client_id}

3. 3

   Authenticate API Requests

   Send the Access Token in the Authorization header when calling protected endpoints.

   httpCopy

   Authorization: Bearer <access_token>

4. 4

   Refresh Expired Tokens

   When the Access Token expires, call the New Access Token endpoint using the Refresh Token to receive a new token pair.

5. 5

   Authenticate End Users

   For Conversations, Messages, and other user-level APIs, authenticate the end user using Login Client User. This returns a separate User Access Token.

Include the following header with every authenticated request:

Authorization: Bearer <accessToken>

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

Always refer to the endpoint documentation to determine whether authentication is required.

If authentication fails, the API returns an appropriate HTTP status code and error response.

Missing Authorization Header

HTTP Status

Error Response

{
  "success": false,
  "message": "Authorization header is missing.",
  "data": null,
  "error": "Unauthorized"
}

HTTP Status

Error Response

{
  "success": false,
  "message": "Invalid or expired access token.",
  "data": null,
  "error": "Unauthorized"
}

HTTP Status

Error Response

{
  "success": false,
  "message": "You do not have permission to access this resource.",
  "data": null,
  "error": "Forbidden"
}

• Never expose access tokens in client-side source code.
• Always transmit API requests over HTTPS.
• Store tokens securely using your application's recommended storage mechanism.
• Avoid logging sensitive authentication credentials.
• Immediately revoke or replace compromised tokens.
• Follow the principle of least privilege when assigning user roles and permissions.

Once authentication is configured successfully, you can begin exploring the available API modules, including Users, Conversations, Messages, Roles, and other protected resources available in the RealtimeX API.