# 2단계 인증

Pocket Alert는 웹 대시보드와 모바일 앱 모두에서 TOTP 기반 2단계 인증을 지원해요. 한 번 켜 두면 비밀번호만으로는 계정에 로그인할 수 없어요.

[계정 → 보안](https://pocketalert.app/account/security)에서 설정할 수 있어요.

## 설정하기

1. **계정 → 보안**을 열고 설정을 시작하세요. QR 코드와 비밀 키가 표시돼요.
2. Google Authenticator, 1Password, Authy, Bitwarden 등 원하는 TOTP 인증 앱으로 QR 코드를 스캔하세요.
3. 여섯 자리 코드를 입력해 확인하세요. 올바른 코드를 입력해야 비로소 2단계 인증이 켜져요.
4. 화면에 표시된 복구 코드를 저장하세요. 각 코드는 한 번만 사용할 수 있어요.

> **Tip: 설정 중단은 안전해요**
>
> 새로 설정을 시작해도 기존 2단계 인증에는 영향이 없어요. 새 비밀 키는 대기 슬롯에 저장되고, 코드를 확인한 뒤에만 기존 키를 대체해요. 그래서 설정 도중 탭을 닫아도 계정이 잠기지 않아요.

## 로그인 방식의 변화

2단계 인증을 켜면 `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: 스크립트는 계속 동작해요**
>
> 2단계 인증은 직접 하는 로그인에 적용돼요. [API 키](https://pocketalert.app/account/apikeys)에서 발급한 키는 `Token` 헤더로 인증하며 2단계 인증을 요구하지 않아요. 크론 작업, CI 파이프라인, 모니터링 훅은 지금까지와 똑같이 알림을 보낼 수 있어요.
>
> 그래서 API 키는 서비스별로 나눠 발급해 두는 것이 좋아요. 키 하나를 폐기해도 다른 키에는 영향이 없어요.

## 복구 코드

복구 코드는 한 번만 쓸 수 있고, 사용과 동시에 원자적으로 소진돼요. 같은 코드로 두 로그인을 동시에 시도해도 한 번만 성공해요. **계정 → 보안**에서 언제든 새 코드를 발급받을 수 있어요. 새 코드를 발급하면 기존 코드는 모두 무효화돼요.

인증 앱과 복구 코드를 모두 잃어버렸다면 고객 지원팀에 문의해 주세요. 셀프 서비스로 우회할 수 있는 방법은 없어요. 이것이 바로 설계 의도예요.

## 무차별 대입 공격 방어

코드를 다섯 번 연속으로 틀리면 계정이 **15분** 동안 잠기고, 그 사이의 시도는 모두 `429`를 반환해요. 카운터는 로그인에 성공하거나 2단계 인증을 켜거나 끌 때 초기화돼요. 챌린지는 5분 동안 그대로 유효하기 때문에, 여섯 자리 코드를 추측하기 어려운 이유는 챌린지 수명이 아니라 이 시도 횟수 제한이에요.

## 이메일 알림

계정에서 2단계 인증을 켜거나 끌 때마다 이메일을 받아요. 본인이 한 일이 아닌데 이메일이 왔다면 즉시 비밀번호를 변경하세요.

## 엔드포인트

| Method | Endpoint | 용도 |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | 2단계 인증 활성화 여부와 남은 복구 코드 수 |
| `POST` | `/v1/auth/2fa/setup` | 등록 시작 — 비밀 키와 QR 페이로드를 반환 |
| `POST` | `/v1/auth/2fa/enable` | 코드를 확인하고 2단계 인증 활성화 |
| `POST` | `/v1/auth/2fa/disable` | 2단계 인증 끄기 — 코드와 비밀번호가 필요 |
| `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) — 인증 개요
