13.5.13 Двухфакторная аутентификация

Методы

twofa-enable

Метод включения двухфакторной аутентификации для пользователя.

При включении двухфакторной аутентификации на email будет отправлен код подтверждения. Для успешного завершения операции необходимо повторно вызвать метод с параметром code. Если параметр code не указан, то будет отправлен новый код и вернётся ошибка с требованием его ввести.

• type — тип отправки кода, на данный момент только email;
• email — адрес электронной почты;
• code — необязательный параметр.

Запрос (1 шаг — запросить код):

{
    "jsonrpc": "2.0",
    "method": "twofa-enable",
    "params": {
        "type": "email",
        "email": "user@example.com"
    },
    "id": "5df98e2f-1cb0-4a44-98c1-dc16adf32f87"
}

Ответ при необходимости кода:

• expires_at — timestamp в UTC, когда код будет недействителен;
• next_at — timestamp в UTC, когда можно будет отправить новый код.

{
    "jsonrpc": "2.0",
    "id": "5df98e2f-1cb0-4a44-98c1-dc16adf32f87",
    "error": {
        "code": -32403,
        "message": "Confirmation code was sent to your email address.",
        "data": {
            "code": {
                "expires_at": 1756303039,
                "next_at": 1756302439
            },
            "email_hint": "u***@example.com"
        }
    }
}

Запрос (2 шаг — подтверждение с кодом ):

{
    "jsonrpc": "2.0",
    "method": "twofa-enable",
    "params": {
        "type": "email",
        "email": "user@example.com",
        "code": "123456"
    },
    "id": "e84b6c97-15f0-4d9a-b421-14770b6e1131"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "e84b6c97-15f0-4d9a-b421-14770b6e1131",
    "result": {
        "code": 1,
        "message": "2FA was enabled."
    }
}

twofa-disable

Метод выключения двухфакторной аутентификации для пользователя.

Выключение также требует подтверждения кодом, который будет отправлен на email. Если код не указан, то будет отправлен новый код и вернётся ошибка с требованием его ввести.

Запрос (1 шаг — запросить код):

• type — email (тип отправки кода);
• code — необязательный параметр.

{
    "jsonrpc": "2.0",
    "method": "twofa-disable",
    "params": {
        "type": "email"
    },
    "id": "5df98e2f-1cb0-4a44-98c1-dc16adf32f87"
}

Ответ при необходимости кода:

• expires_at — timestamp в UTC, когда код будет недействителен;
• next_at — timestamp в UTC, когда можно будет отправить новый код.

{
    "jsonrpc": "2.0",
    "id": "5df98e2f-1cb0-4a44-98c1-dc16adf32f87",
    "error": {
        "code": -32403,
        "message": "Confirmation code was sent to your email address.",
        "data": {
            "code": {
                "expires_at": 1756303039,
                "next_at": 1756302439
            },
            "email_hint": "u***@example.com"
        }
    }
}

Запрос (2 шаг — подтверждение с кодом):

{
    "jsonrpc": "2.0",
    "method": "twofa-disable",
    "params": {
        "type": "email",
        "code": "123456"
    },
    "id": "e84b6c97-15f0-4d9a-b421-14770b6e1131"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "e84b6c97-15f0-4d9a-b421-14770b6e1131",
    "result": {
        "code": 1,
        "message": "2FA was disabled."
    }
}

Ошибки двухфакторной аутентификации

Все ошибки, связанные с двухфакторной аутентификацией, имеют уникальный код.

Ошибки при управлении двухфакторной аутентификацией

Попытка включить уже включенную двухфакторную аутентификацию

{
  "jsonrpc": "2.0",
  "id": "4a19c02f-9a5b-44f7-9e6a-9a9fcd1b087e",
  "error": {
    "code": -32401,
    "message": "2FA is already enabled and verified. Please disable 2FA before updating the email."
  }
}

Попытка выключить уже выключенную двухфакторную аутентификацию

{
  "jsonrpc": "2.0",
  "id": "e7818a9b-2a41-4aef-9fc9-fb93a7ad019e",
  "error": {
    "code": -32400,
    "message": "2FA is already disabled. Please enable 2FA before updating the email."
  }
}

Ошибки при проверке кода

Код не найден

Причина: code указан, но код ранее не запрашивался или уже был использован и удалён.

{
  "jsonrpc": "2.0",
  "id": "deae942f-9d49-44ab-82f4-23c1b46b7e42",
  "error": {
    "code": -32404,
    "message": "Confirmation code does not exist. Please request a new one"
  }
}

Код истёк

Код устарел и удаляется.

{
  "jsonrpc": "2.0",
  "id": "fbb2c694-f5ef-4c76-8c02-b3903a82cf6c",
  "error": {
    "code": -32405,
    "message": "Confirmation code has expired. Please request a new one"
  }
}

Неверный код

Если попытки указать код заканчиваются, то код удаляется.

{
  "jsonrpc": "2.0",
  "id": "83c75843-51d7-4b32-bb92-4a1b5821a328",
  "error": {
    "code": -32406,
    "message": "Invalid confirmation code.",
    "data": {
      "attempts_left": 2
    }
  }
}

Ошибки при отправке кода

Интервал не истёк

Код нельзя запрашивать чаще установленного интервала.

{
  "jsonrpc": "2.0",
  "id": "52eb9d88-ccf5-49ee-9e45-949b1db2d9e1",
  "error": {
    "code": -32402,
    "message": "Confirmation code request interval not elapsed.",
    "data": {
      "retry_after": "2025-08-27T12:00:00Z"
    }
  }
}

Код отправлен

Метод требует двухфакторной аутентификации, но код ещё не предоставлен. Отправлен новый код на email.

{
  "jsonrpc": "2.0",
  "id": "c3d85f0a-908d-4e47-8990-c4d3442cfe53",
  "error": {
    "code": -32403,
    "message": "Confirmation code was sent to your email address.",
    "data": {
        "code": {
            "expires_at": 1756303039,
            "next_at": 1756302439
        },
        "email_hint": "u***@gmail.com"
    }
  }
}

Параметры:

• expires_at — timestamp в UTC, когда код будет недействителен;
• next_at — timestamp в UTC, когда можно будет отправить новый код.

Сводная таблица ошибок двухфакторной аутентификации

Таблица 1. Ошибки двухфакторной аутентификации

Сценарий	Код ошибки	Message	Что происходит с кодом	Дополнительные данные
Выключение при уже выключенной двухфакторной аутентификации	-32400	2FA is already disabled. Please enable 2FA before updating the email	—	—
Включение при уже включенной двухфакторной аутентификации	-32401	2FA is already enabled and verified. Please disable 2FA before updating	—	—
Интервал не истёк	-32402	Confirmation code request interval not elapsed	—	retry_after (UTC)
Код отправлен	-32403	Confirmation code was sent to your email address	—	email_hint, code.expires_at, code.next_at
Код не найден	-32404	Confirmation code does not exist. Please request a new one	Не существовал/удалён	—
Код истёк	-32405	Confirmation code has expired. Please request a new one	Код удаляется	—
Неверный код	-32406	Invalid confirmation code	Попытки уменьшаются/удаляется при 0	attempts_left