# 双重身份验证

Pocket Alert 在网页控制台和移动应用中都支持基于 TOTP 的双重身份验证。开启后，仅凭密码将无法登录你的账户。

在 [账户 → 安全](https://pocketalert.app/account/security) 中进行设置。

## 设置方法

1. 打开 **账户 → 安全**，开始设置。你会看到一个二维码和一串密钥。
2. 使用任意 TOTP 验证器扫描，例如 Google Authenticator、1Password、Authy、Bitwarden。
3. 输入六位数验证码以完成确认。只有输入正确的验证码后，双重身份验证才会真正生效。
4. 保存显示的恢复码。每个恢复码只能使用一次。

> **Tip: 中途中断设置是安全的**
>
> 开始新的设置不会影响你现有的双重身份验证。新密钥会先放在待定位置，只有在你确认验证码之后才会替换当前生效的密钥，因此即使设置到一半关闭了页面，你也不会被锁在外面。

## 登录流程的变化

开启双重身份验证后，`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: 脚本照常运行**
>
> 双重身份验证只作用于交互式登录。来自 [API 密钥](https://pocketalert.app/account/apikeys) 的密钥通过 `Token` 请求头进行认证，不会触发验证。你的 cron 任务、CI 流水线和监控回调会像以前一样继续发送告警。
>
> 这也是为什么值得为每个服务单独划分 API 密钥的权限范围：撤销其中一个，不会影响其他密钥。

## 恢复码

恢复码只能使用一次，并且以原子方式消耗：两个并发登录无法同时使用同一个恢复码。你可以随时在 **账户 → 安全** 中生成一组新的恢复码；签发新码后，旧码会失效。

如果验证器和恢复码都丢失了，请联系支持团队。系统不提供自助绕过方式，这正是设计初衷。

## 暴力破解防护

连续五次验证码错误会将账户锁定 **15 分钟**，锁定期间的尝试将返回 `429`。登录成功，或开启/关闭双重身份验证时，计数器会重置。由于挑战令牌在完整的五分钟内都有效，正是这个尝试次数限制，而不是挑战令牌的有效期，使得猜测六位数验证码变得不切实际。

## 邮件通知

每当你的账户上开启或关闭双重身份验证时，你都会收到一封邮件。如果收到的邮件不是你本人操作的，请立即修改密码。

## 接口端点

| 方法 | 端点 | 用途 |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | 双重身份验证是否已开启，以及剩余多少个恢复码 |
| `POST` | `/v1/auth/2fa/setup` | 开始注册流程，返回密钥和二维码数据 |
| `POST` | `/v1/auth/2fa/enable` | 确认验证码并启用双重身份验证 |
| `POST` | `/v1/auth/2fa/disable` | 关闭双重身份验证，需要验证码和密码 |
| `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) — 认证概览
