API Documentation
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
POSTrequest to/users/self/mfa/setup. This endpoint will return two important fields,mfa_urlandmfa_qr_code, which can be used with an authenticator application to add a new service. -
Verify MFA:
POST /users/self/mfa/verifyAfter 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 callPOST /users/self/mfa/validatewith a valid MFA token generated by the authenticator application to mark the tokens as MFA validated. -
Delete MFA:
DELETE /users/self/mfaendpoint with a valid MFA token can be used to remove the multi-factor authentication from the user.
Setup MFA ¶
Setup MFAPOST/users/self/mfa/setup
Example URI
200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+16736549511",
"created_at": 1783015002.034736,
"id": "2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7/62c179a0-763f-11f1-94b5-7519f45a456b.jpg",
"profile_image_url": "https://test.cloudfront.net/2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7/62c5bf60-763f-11f1-94b5-7519f45a456b.jpg",
"updated_at": 1783015003.74119,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": false,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": false,
"is_shadow": false,
"personal_room": "4272b98c-e3e6-4fb6-9af8-0695a6080e6a",
"brand": null,
"fake_email": null,
"features": null,
"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": null,
"bio": "Here is my great bio",
"current_time": "12:56 PM - Thursday Jul 02, 2026",
"push_allowed": true,
"agents": [
{
"id": "8b3f74c2-0897-4ca8-b5f3-9a30c8e925fa",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "+19722644703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "+14693588080",
"generational_name": null,
"matrix_unique_id": "1891130259",
"updated_at": 1783015002.168674,
"deleted_at": null,
"created_at": 1783015002.168674,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"+1XXXXXXXX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Doe",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"mfa_url": "otpauth://totp/Rechat:test-user-539830b8-3386-4799-a8fd-3c61fc3ed314%40rechat.com?issuer=Rechat&secret=PMSDR263OH2GOEOON5LIHH7LGAJBH3AD&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 setupPOST/users/self/mfa/verify
Example URI
Body
{
"token": "381810"
}200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+16736549511",
"created_at": 1783015002.034736,
"id": "2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7/62c179a0-763f-11f1-94b5-7519f45a456b.jpg",
"profile_image_url": "https://test.cloudfront.net/2b31d3b5-18e9-46a8-9bd5-f53d8b34b2b7/62c5bf60-763f-11f1-94b5-7519f45a456b.jpg",
"updated_at": 1783015003.74119,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": false,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": false,
"is_shadow": false,
"personal_room": "4272b98c-e3e6-4fb6-9af8-0695a6080e6a",
"brand": null,
"fake_email": null,
"features": null,
"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": null,
"bio": "Here is my great bio",
"current_time": "12:56 PM - Thursday Jul 02, 2026",
"push_allowed": true,
"agents": [
{
"id": "8b3f74c2-0897-4ca8-b5f3-9a30c8e925fa",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "+19722644703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "+14693588080",
"generational_name": null,
"matrix_unique_id": "1891130259",
"updated_at": 1783015002.168674,
"deleted_at": null,
"created_at": 1783015002.168674,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"+1XXXXXXXX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Doe",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"has_password": true
}
}