Справочник MFA API

Полный справочник MFA Verification API. Все пользовательские endpoints требуют user access token со scope mfa:verify. Management endpoints требуют M2M токен.

Базовый URL: https://app.voxkey.io/api/v1/{realmUUID}

---

Список MFA факторов

Возвращает зарегистрированные MFA факторы пользователя и доступные (ещё не зарегистрированные) типы факторов.

GET /mfa/factors

Заголовки:

Заголовок	Значение
Authorization	Bearer <user_access_token>

Ответ 200 OK:

{
  "enrolled": [
    {
      "type": "totp",
      "created_at": "2026-01-15T12:00:00Z"
    },
    {
      "type": "email",
      "created_at": "2026-02-01T09:00:00Z",
      "destination": "t***@example.com"
    }
  ],
  "available": ["sms", "webauthn", "backup_code"]
}

---

Создание MFA challenge

Создаёт новый challenge для определённого типа фактора. Для email и sms факторов запускает отправку одноразового кода.

POST /mfa/challenges

Тело запроса:

Параметр	Тип	Обязательный	Описание
factor_type	string	Да	Один из: totp, email, sms, webauthn, backup_code
purpose	string	Да	Идентификатор действия, напр. account.delete. Паттерн: /^[a-z][a-z0-9_.]{2,50}$/
resource_id	string	Нет	Опциональный идентификатор ресурса для аудита
issue_step_up_token	boolean	Нет	Вернуть подписанный JWT после верификации. По умолчанию: false

Пример запроса:

curl -X POST https://app.voxkey.io/api/v1/{realmUUID}/mfa/challenges \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "factor_type": "totp",
    "purpose": "password.change",
    "issue_step_up_token": true
  }'

Ответ по типу фактора

TOTP -- 201 Created:

{
  "challenge_id": "550e8400-e29b-41d4-a716-446655440000",
  "factor_type": "totp",
  "purpose": "password.change",
  "expires_at": "2026-04-03T10:05:00Z",
  "challenge_type": "code"
}

Email -- 201 Created:

{
  "challenge_id": "550e8400-e29b-41d4-a716-446655440001",
  "factor_type": "email",
  "purpose": "password.change",
  "expires_at": "2026-04-03T10:05:00Z",
  "challenge_type": "code",
  "delivery": {
    "destination": "t***@example.com",
    "sent": true
  }
}

WebAuthn -- 201 Created:

{
  "challenge_id": "550e8400-e29b-41d4-a716-446655440003",
  "factor_type": "webauthn",
  "purpose": "password.change",
  "expires_at": "2026-04-03T10:05:00Z",
  "challenge_type": "webauthn",
  "webauthn_options": {
    "challenge": "base64url-encoded-challenge",
    "allowCredentials": [...],
    "userVerification": "required"
  }
}

Ошибка 422 -- Фактор не зарегистрирован:

{
  "error": "factor_not_enrolled",
  "message": "User does not have totp factor enrolled",
  "available_factors": ["email", "backup_code"]
}

Rate limit: 5 challenge в минуту на пользователя+клиент. Превышение возвращает 429.

---

Верификация MFA challenge

Отправляет код верификации (или WebAuthn assertion) для завершения challenge.

POST /mfa/challenges/{challengeId}/verify

Тело запроса (TOTP / Email / SMS / Backup code)

{ "code": "123456" }

Тело запроса (WebAuthn)

{
  "credential": {
    "id": "base64url...",
    "rawId": "base64url...",
    "response": {
      "authenticatorData": "base64url...",
      "clientDataJSON": "base64url...",
      "signature": "base64url..."
    },
    "type": "public-key"
  }
}

Успешный ответ 200 OK

Без step-up токена:

{
  "verified": true,
  "factor_type": "totp",
  "verified_at": "2026-04-03T10:04:30Z"
}

Со step-up токеном (когда issue_step_up_token: true был указан в challenge):

{
  "verified": true,
  "factor_type": "totp",
  "verified_at": "2026-04-03T10:04:30Z",
  "step_up_token": "eyJhbGciOiJSUzI1NiIs..."
}

---

Коды ошибок

Статус	Код ошибки	Значение
410	mfa.challenge_expired	TTL challenge истёк (5 минут)
410	mfa.challenge_not_active	Challenge уже верифицирован или заблокирован
410	mfa.challenge_max_attempts	5 неудачных попыток -- challenge заблокирован
422	invalid_code	Неверный код верификации. Ответ содержит attempts_remaining
422	factor_not_enrolled	Пользователь не зарегистрировал этот тип фактора. Ответ содержит available_factors
429	--	Превышен rate limit

---

Management API

Эти endpoints требуют M2M токен (не пользовательский).

Список MFA факторов пользователя

GET /api/v1/{realmUUID}/users/{userId}/mfa-factors
Authorization: Bearer <m2m_token>

Требуемый scope: mfa:read

Удаление MFA фактора пользователя

DELETE /api/v1/{realmUUID}/users/{userId}/mfa-factors/{type}
Authorization: Bearer <m2m_token>

Требуемый scope: mfa:write

Ответ 204 -- Фактор удалён.