Two-Factor Authentication

Prev Next

Rocket.Chat offers various methods for two-factor authentication in a workspace. Refer to the Two-Factor Authentication guide for more details.

To enable email two-factor authentication (2FA), ensure that SMTP is configured in your workspace. If you don't have the necessary permissions, contact your workspace administrator.

When making requests to endpoints that require two-factor authentication, add the following headers to the request:

  • x-2fa-code: (string) The 2FA code.

  • x-2fa-method: (string) The desired method to check for the 2FA code, usually returned in the 2FA error (it can be email, totp, or password).

If you attempt to send a request to certain endpoints without the appropriate 2FA headers, you receive an error of type totp-required. The error message includes a details object, that specifies the required 2FA method. It's useful for informing the user how to obtain their 2FA code.

The parameters of the details object are as follows:

  • method: The required 2FA method for the user selected in the workspace.

  • codeGenerated: Used to inform if the code was generated or if there are tokens available already. It is specific to 2FA by Email.

  • codeCount: (optional) The number of available codes already sent via email. It is specific to 2FA by email.

  • codeExpires: (optional) A list of expiration dates of the tokens. It is specific to 2FA by email.

  • availableMethods: The list of available 2FA methods for the user's account.

The following example shows a 2FA error:

{
  "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"
    ]
  }
}

If the 2FA code is wrong, a totp-invalid response is returned:

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

Handling 2FA method errors

It's important to note the required TOTP method returned in the error response when making requests that require 2FA.

  • If the method is password, add the hashed password of the user as the X-2fa-Code header parameter.

  • If it's email, add the 2FA code sent via email as the X-2fa-Code header parameter.

  • If it's totp, add the code from your authenticator app as the X-2fa-Code header parameter.