본문으로 건너뛰기

2단계 인증 ​

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

계정 → 보안에서 설정할 수 있어요.

설정하기 ​

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

설정 중단은 안전해요

새로 설정을 시작해도 기존 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 키에는 영향이 없어요 ​

스크립트는 계속 동작해요

2단계 인증은 직접 하는 로그인에 적용돼요. API 키에서 발급한 키는 Token 헤더로 인증하며 2단계 인증을 요구하지 않아요. 크론 작업, CI 파이프라인, 모니터링 훅은 지금까지와 똑같이 알림을 보낼 수 있어요.

그래서 API 키는 서비스별로 나눠 발급해 두는 것이 좋아요. 키 하나를 폐기해도 다른 키에는 영향이 없어요.

복구 코드 ​

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

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

무차별 대입 공격 방어 ​

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

이메일 알림 ​

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

엔드포인트 ​

MethodEndpoint용도
GET/v1/auth/2fa/status2단계 인증 활성화 여부와 남은 복구 코드 수
POST/v1/auth/2fa/setup등록 시작 — 비밀 키와 QR 페이로드를 반환
POST/v1/auth/2fa/enable코드를 확인하고 2단계 인증 활성화
POST/v1/auth/2fa/disable2단계 인증 끄기 — 코드와 비밀번호가 필요
POST/v1/auth/2fa/recovery-codes새 복구 코드 세트 발급
POST/v1/auth/2fa/login챌린지와 코드를 JWT로 교환 (인증 헤더 불필요)

/auth/2fa/login을 제외한 모든 엔드포인트는 인증된 세션이 필요해요.

관련 문서 ​

Pocket Alert 문서