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

Pocket Alert поддерживает двухфакторную аутентификацию по TOTP в веб-панели и в мобильном приложении. После включения один только пароль больше не открывает доступ к вашему аккаунту.

Настроить её можно в разделе [Аккаунт → Безопасность](https://pocketalert.app/account/security).

## Настройка

1. Откройте **Аккаунт → Безопасность** и запустите настройку. Вы получите QR-код и секретный ключ.
2. Отсканируйте его любым TOTP-приложением: Google Authenticator, 1Password, Authy, Bitwarden.
3. Введите шестизначный код для подтверждения. Только после правильного кода 2FA действительно включается.
4. Сохраните резервные коды, которые вам покажут. Каждый из них работает один раз.

> **Tip: Прерванная настройка безопасна**
>
> Запуск новой настройки не затрагивает текущую двухфакторную аутентификацию. Новый секрет сохраняется в ожидающем слоте и заменяет действующий только после подтверждения кода, поэтому закрытие вкладки на полпути не заблокирует вас.

## Как меняется вход

Если 2FA включена, `POST /v1/auth/login` больше не возвращает JWT. Вместо него возвращается недолговечный челлендж:

```json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}
```

Обменяйте челлендж и код на настоящий токен:

```
POST https://api.pocketalert.app/v1/auth/2fa/login
```

```bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'
```

Успешный обмен возвращает те же данные, что и обычный вход: `token`, `name`, `email`, `avatar`. Поле `code` принимает либо шестизначный TOTP-код, либо один из ваших резервных кодов.

Челленджи действуют **5 минут**.

## API-ключи не затронуты

> **Info: Скрипты продолжают работать**
>
> 2FA применяется к интерактивному входу. API-ключи из раздела [API-ключи](https://pocketalert.app/account/apikeys) проходят аутентификацию через заголовок `Token` и не требуют второго фактора. Ваши cron-задачи, CI-пайплайны и хуки мониторинга продолжают отправлять уведомления как прежде.
>
> Поэтому API-ключи стоит выдавать отдельно для каждого сервиса: отзыв одного из них не влияет на остальные.

## Резервные коды

Резервные коды одноразовые и расходуются атомарно: два параллельных входа не могут использовать один и тот же код. Новый набор можно создать в любой момент в разделе **Аккаунт → Безопасность**. Выпуск новых кодов делает старые недействительными.

Потеряли и приложение-аутентификатор, и коды? Обратитесь в поддержку. Самостоятельного обхода нет, и это намеренно.

## Защита от перебора

Пять неверных кодов блокируют аккаунт на **15 минут**, а дальнейшие попытки возвращают `429`. Счётчик сбрасывается при успешном входе, а также при включении или отключении 2FA. Поскольку челлендж действует все пять минут, именно этот лимит попыток, а не время жизни челленджа, делает подбор шестизначного кода непрактичным.

## Уведомления на email

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

## Эндпоинты

| Метод | Эндпоинт | Назначение |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | Включена ли 2FA и сколько резервных кодов осталось |
| `POST` | `/v1/auth/2fa/setup` | Начать регистрацию: возвращает секрет и данные для QR-кода |
| `POST` | `/v1/auth/2fa/enable` | Подтвердить код и активировать 2FA |
| `POST` | `/v1/auth/2fa/disable` | Отключить 2FA: нужны код и пароль |
| `POST` | `/v1/auth/2fa/recovery-codes` | Выпустить новый набор резервных кодов |
| `POST` | `/v1/auth/2fa/login` | Обменять челлендж и код на JWT (без заголовка авторизации) |

Все эндпоинты, кроме `/auth/2fa/login`, требуют авторизованной сессии.

## Связанное

- [Вход](https://info.pocketalert.app/api/user/login.md) — первый шаг процесса входа
- [Введение](https://info.pocketalert.app/intro.md) — обзор аутентификации
