2단계 인증
Pocket Alert는 웹 대시보드와 모바일 앱 모두에서 TOTP 기반 2단계 인증을 지원해요. 한 번 켜 두면 비밀번호만으로는 계정에 로그인할 수 없어요.
계정 → 보안에서 설정할 수 있어요.
설정하기
- 계정 → 보안을 열고 설정을 시작하세요. QR 코드와 비밀 키가 표시돼요.
- Google Authenticator, 1Password, Authy, Bitwarden 등 원하는 TOTP 인증 앱으로 QR 코드를 스캔하세요.
- 여섯 자리 코드를 입력해 확인하세요. 올바른 코드를 입력해야 비로소 2단계 인증이 켜져요.
- 화면에 표시된 복구 코드를 저장하세요. 각 코드는 한 번만 사용할 수 있어요.
설정 중단은 안전해요
새로 설정을 시작해도 기존 2단계 인증에는 영향이 없어요. 새 비밀 키는 대기 슬롯에 저장되고, 코드를 확인한 뒤에만 기존 키를 대체해요. 그래서 설정 도중 탭을 닫아도 계정이 잠기지 않아요.
로그인 방식의 변화
2단계 인증을 켜면 POST /v1/auth/login은 더 이상 JWT를 반환하지 않아요. 대신 수명이 짧은 챌린지를 반환해요.
{
"two_factor_required": true,
"challenge": "eyJhbGciOiJIUzI1NiIs…"
}챌린지와 코드를 함께 보내면 실제 토큰을 받을 수 있어요.
POST https://api.pocketalert.app/v1/auth/2fa/logincurl -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 키에는 영향이 없어요
스크립트는 계속 동작해요
2단계 인증은 직접 하는 로그인에 적용돼요. API 키에서 발급한 키는 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을 제외한 모든 엔드포인트는 인증된 세션이 필요해요.