Back to top

API Documentation

Authorize

Overview

We currently allow applications to authenticate with OAuth 2 protocol. OAuth2 has different strategies and Rechat supports two of them:

Strategy Use case
Bearer (AccessToken) User login required
ClientPassword User login makes no sense in the context (eg Registration, where user has no credentials to begin with)

The ClientPassword authentication method is only reserved for for Rechat’s internal applications. Partners trying to create integrations should use OAuth process to fetch new tokens.

You should use a third party library for handling the whole process.

If you are writing code to handle these steps, you are most probably doing it wrong.

Authentication

Get Token
POST/oauth2/token

Basically, login in rechat (and other oauth2 based API’s) means fetching access_token from the server and providing it in the HTTP headers for the remainder of the session like this:

Authorization: Bearer <fetched_access_token>

Additional to access_token, this endpoint will give you:

  • Profile of the logged in user.

  • Expirey date of the access token

  • A refresh token

Example URI

POST /oauth2/token
Request
HideShow
Body
{
  "client_id": "bf0da47e-7226-11e4-905b-0024d71b10fc",
  "client_secret": "secret",
  "username": "[email protected]",
  "password": "aaaaaa",
  "grant_type": "password"
}
Response  200
HideShow
Body
{
  "access_token": "NmEwNWFlOWMtZDNlMy0xMWYwLWFkMjctNWUyOWI5ODQyZmRl",
  "refresh_token": "NmEwNGNhYzItZDNlMy0xMWYwLWFkMjctNWUyOWI5ODQyZmRl",
  "expires_in": 2678400,
  "code": "OK",
  "data": {
    "type": "user",
    "username": null,
    "first_name": "Unit",
    "last_name": "Test",
    "email": "[email protected]",
    "phone_number": "+4368120265807",
    "created_at": 1493115498.770362,
    "id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "address_id": null,
    "cover_image_url": null,
    "profile_image_url": null,
    "updated_at": 1493115498.770744,
    "user_status": "Active",
    "profile_image_thumbnail_url": null,
    "cover_image_thumbnail_url": null,
    "email_confirmed": true,
    "timezone": "America/Chicago",
    "user_type": "Admin",
    "deleted_at": null,
    "phone_confirmed": false,
    "is_shadow": false,
    "personal_room": null,
    "brand": null,
    "fake_email": false,
    "features": [
      "Deals"
    ],
    "last_seen_at": null,
    "email_signature": null,
    "daily_enabled": false,
    "email_quota": 30000,
    "website": null,
    "instagram": null,
    "twitter": null,
    "linkedin": null,
    "youtube": null,
    "facebook": null,
    "designation": null,
    "tiktok": null,
    "mfa_enabled": false,
    "xpressdocs_user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "current_time": "9:10 PM - Sunday Dec 07, 2025",
    "push_allowed": true,
    "agents": null,
    "last_seen_type": null,
    "active_brand": null,
    "display_name": "Unit Test",
    "abbreviated_display_name": "Unit",
    "online_state": "Offline",
    "has_password": true
  },
  "token_type": "Bearer"
}

Refresh Token
POST/oauth2/token

An access token has a expiry date and thus will be expired. But every time you get an access token (as documented above), you will be given a refresh token which has a longer expiry.

At any time, you can exchange the refresh token with a new pair of tokens like this:

Example URI

POST /oauth2/token
Request
HideShow
Body
{
  "refresh_token": "NmEwNGNhYzItZDNlMy0xMWYwLWFkMjctNWUyOWI5ODQyZmRl",
  "grant_type": "refresh_token",
  "client_id": "bf0da47e-7226-11e4-905b-0024d71b10fc",
  "client_secret": "secret"
}
Response  200
HideShow
Body
{
  "access_token": "NmEwY2Q2MGUtZDNlMy0xMWYwLWFkMjctNWUyOWI5ODQyZmRl",
  "refresh_token": "NmEwYzAxYTItZDNlMy0xMWYwLWFkMjctNWUyOWI5ODQyZmRl",
  "expires_in": 2678400,
  "code": "OK",
  "token_type": "Bearer"
}

Multi-factor authentication

Overview

MFA is an opt-in feature, allowing users to set it up in their account settings. Once MFA is activated, MFA will be required when making certain API requests, such as changing the password.

  • Setup MFA: To get started, make a POST request to /users/self/mfa/setup. This endpoint will return two important fields, mfa_url and mfa_qr_code, which can be used with an authenticator application to add a new service.

  • Verify MFA: POST /users/self/mfa/verify After setting up MFA, it’s not immediately enabled for the user. We require users to verify it first by providing a token. The verification step enables the MFA for the user and also marks the current access_token/refresh_token pair as MFA validated.

  • Validate MFA: If a user with verified MFA needs to sign in again, the new access_token/refresh_token pair won’t be MFA validated by default. This means that every request made with the access token will result in a 401 MFA required error. In such cases, the client must call POST /users/self/mfa/validate with a valid MFA token generated by the authenticator application to mark the tokens as MFA validated.

  • Delete MFA: DELETE /users/self/mfa endpoint with a valid MFA token can be used to remove the multi-factor authentication from the user.

Setup MFA

Setup MFA
POST/users/self/mfa/setup

Example URI

POST /users/self/mfa/setup
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "type": "user",
    "username": null,
    "first_name": "updated first name",
    "last_name": "Test",
    "email": "[email protected]",
    "phone_number": "+4368120265807",
    "created_at": 1493115498.770362,
    "id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "address_id": null,
    "cover_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/02fa07b0-d3e4-11f0-a2d4-1bcac3894d4e.jpg",
    "profile_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/030181c0-d3e4-11f0-a2d4-1bcac3894d4e.jpg",
    "updated_at": 1765163670.502189,
    "user_status": "Active",
    "profile_image_thumbnail_url": null,
    "cover_image_thumbnail_url": null,
    "email_confirmed": true,
    "timezone": "America/Chicago",
    "user_type": "Agent",
    "deleted_at": null,
    "phone_confirmed": true,
    "is_shadow": false,
    "personal_room": null,
    "brand": null,
    "fake_email": false,
    "features": [
      "Deals"
    ],
    "last_seen_at": null,
    "email_signature": "Here is my great signature",
    "daily_enabled": true,
    "email_quota": 30000,
    "website": null,
    "instagram": null,
    "twitter": null,
    "linkedin": null,
    "youtube": null,
    "facebook": null,
    "designation": null,
    "tiktok": null,
    "mfa_enabled": false,
    "xpressdocs_user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "current_time": "9:14 PM - Sunday Dec 07, 2025",
    "push_allowed": true,
    "agents": [
      {
        "id": "f7e5a65a-50b5-4249-8b2e-bea7d2115db5",
        "email": "[email protected]",
        "mlsid": "00920130",
        "fax": "(972) 264-4703",
        "full_name": "Gholi Sweet",
        "first_name": "Gholi",
        "last_name": "Sweet",
        "middle_name": null,
        "phone_number": "(972) 264-4703",
        "nar_number": "797500044",
        "office_mui": "15512742",
        "status": "Active",
        "office_mlsid": "RCHT01X",
        "work_phone": "(469) 358-8080",
        "generational_name": null,
        "matrix_unique_id": "155155530",
        "updated_at": 1765163668.498998,
        "deleted_at": null,
        "created_at": 1765163668.498998,
        "mls": "NTREIS",
        "license_number": null,
        "designation": null,
        "nrds": "01053140",
        "type": "agent",
        "office_id": null,
        "secret_questions": [
          "(972) XXX-XX03",
          "jewellxxxxxxxxxxxxxal.net",
          "(469) XXX-XX80"
        ]
      }
    ],
    "last_seen_type": null,
    "active_brand": null,
    "display_name": "updated first name Test",
    "abbreviated_display_name": "updated first name",
    "online_state": "Offline",
    "mfa_url": "otpauth://totp/Rechat:test%40rechat.com?issuer=Rechat&secret=ZGXS7ERE7J72LHBQTILVFKKYWP6B422K&algorithm=SHA1&digits=6&period=30",
    "mfa_qr_code": "data:image/png;base64,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",
    "has_password": true
  }
}

Verify MFA after setup

Verify MFA after setup
POST/users/self/mfa/verify

Example URI

POST /users/self/mfa/verify
Request
HideShow
Body
{
  "token": "218861"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "type": "user",
    "username": null,
    "first_name": "updated first name",
    "last_name": "Test",
    "email": "[email protected]",
    "phone_number": "+4368120265807",
    "created_at": 1493115498.770362,
    "id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "address_id": null,
    "cover_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/02fa07b0-d3e4-11f0-a2d4-1bcac3894d4e.jpg",
    "profile_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/030181c0-d3e4-11f0-a2d4-1bcac3894d4e.jpg",
    "updated_at": 1765163670.502189,
    "user_status": "Active",
    "profile_image_thumbnail_url": null,
    "cover_image_thumbnail_url": null,
    "email_confirmed": true,
    "timezone": "America/Chicago",
    "user_type": "Agent",
    "deleted_at": null,
    "phone_confirmed": true,
    "is_shadow": false,
    "personal_room": null,
    "brand": null,
    "fake_email": false,
    "features": [
      "Deals"
    ],
    "last_seen_at": null,
    "email_signature": "Here is my great signature",
    "daily_enabled": true,
    "email_quota": 30000,
    "website": null,
    "instagram": null,
    "twitter": null,
    "linkedin": null,
    "youtube": null,
    "facebook": null,
    "designation": null,
    "tiktok": null,
    "mfa_enabled": true,
    "xpressdocs_user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "current_time": "9:14 PM - Sunday Dec 07, 2025",
    "push_allowed": true,
    "agents": [
      {
        "id": "f7e5a65a-50b5-4249-8b2e-bea7d2115db5",
        "email": "[email protected]",
        "mlsid": "00920130",
        "fax": "(972) 264-4703",
        "full_name": "Gholi Sweet",
        "first_name": "Gholi",
        "last_name": "Sweet",
        "middle_name": null,
        "phone_number": "(972) 264-4703",
        "nar_number": "797500044",
        "office_mui": "15512742",
        "status": "Active",
        "office_mlsid": "RCHT01X",
        "work_phone": "(469) 358-8080",
        "generational_name": null,
        "matrix_unique_id": "155155530",
        "updated_at": 1765163668.498998,
        "deleted_at": null,
        "created_at": 1765163668.498998,
        "mls": "NTREIS",
        "license_number": null,
        "designation": null,
        "nrds": "01053140",
        "type": "agent",
        "office_id": null,
        "secret_questions": [
          "(972) XXX-XX03",
          "jewellxxxxxxxxxxxxxal.net",
          "(469) XXX-XX80"
        ]
      }
    ],
    "last_seen_type": null,
    "active_brand": null,
    "display_name": "updated first name Test",
    "abbreviated_display_name": "updated first name",
    "online_state": "Offline",
    "has_password": true
  }
}

Validate an MFA token

Validate an MFA token
POST/users/self/mfa/validate

Example URI

POST /users/self/mfa/validate
Request
HideShow
Body
{
  "token": "218861"
}
Response  204

Remove MFA

Remove MFA
DELETE/users/self/mfa

Example URI

DELETE /users/self/mfa
Request
HideShow
Body
{
  "token": "218861"
}
Response  204

Generated by aglio on 08 Dec 2025