Two-Factor Authentication

Prev Next

Rocket.Chat offers several methods for enabling two-factor authentication (2FA) in a workspace. Before using endpoints that require 2FA, ensure that 2FA is enabled by the workspace administrator at: Manage → Workspace → Settings → Accounts → Two Factor Authentication.

For user instructions on setting up 2FA, see the Two-Factor Authentication user guide.

Email-based 2FA requires SMTP to be configured in your workspace.

Using 2FA in API requests

Whenever you call an endpoint that requires two-factor authentication, you must include two additional headers in the request headers:

Header

Description

X-2fa-Code

The 2FA code. This can be an email code, TOTP code from an authenticator app, or hashed password (for password-based 2FA).

X-2fa-Method

The method associated with the code (email, totp, or password). This value is usually provided in the error response when 2FA is required.

2FA error responses

If a request is made without the required 2FA credentials, or with invalid credentials, the server returns an error that includes the 2FA method you must supply. Below are all possible error types.

A. totp-required (2FA required)

Returned when the endpoint requires 2FA but none was supplied.

Example response:

{
  "success": false,
  "error": "TOTP Required [totp-required]",
  "errorType": "totp-required",
  "details": {
    "method": "email",
    "codeGenerated": false,
    "codeCount": 1,
    "codeExpires": ["2020-01-02T13:06:42.408Z"],
    "availableMethods": ["email"]
  }
}

Parameters of the details object.

These fields describe the required 2FA method and available verification options:

  • method: Required 2FA method for the user.

  • codeGenerated: Whether an email token was already generated.

  • codeCount (optional): Number of available codes (email only).

  • codeExpires (optional): Token expiration timestamps (email only).

  • availableMethods: All 2FA methods available for the user.

B. totp-invalid (Wrong 2FA code)

Returned when the user supplied a 2FA code, but the code is incorrect.

Example response:

{
  "success": false,
  "error": "TOTP Invalid [totp-invalid]",
  "errorType": "totp-invalid",
  "details": {
    "method": "email"
  }
}

Other 2FA-related errors

error-invalid-user

Returned when the user is not allowed to use the requested 2FA method. This commonly happens when enabling 2FA by email but the user’s email is not verified.

Example response:

{
  "success": false,
  "error": "You need to verify your emails before setting up 2FA [error-invalid-user]",
  "errorType": "error-invalid-user"
}

Handling 2FA method errors

Use the method returned in the error response to determine how to supply the correct 2FA code:

  • password: Provide the user’s hashed password in the X-2fa-Code header.

  • email: Provide the email-based 2FA code in the X-2fa-Code header.

  • totp: Provide the authenticator app code in the X-2fa-Code header.