---
title: "Two-Factor Authentication"
slug: "two-factor-authentication-api"
updated: 2026-02-16T08:43:50Z
published: 2026-02-16T08:44:35Z
canonical: "developer.rocket.chat/two-factor-authentication-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-Factor Authentication

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**](https://docs.rocket.chat/docs/two-factor-authentication-user-guide) user guide.

> [!WARNING]
> Email-based 2FA requires [SMTP](https://docs.rocket.chat/docs/configure-email) 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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.