# 티스토리 인증 & 자동 발행 리서치 결과

**작성일**: 2026-03-27
**Task**: task-1109.1
**작성자**: 헤르메스 (dev1-team)

---

## 1. 티스토리 Open API v1 현재 상태

### 결론: 완전 폐지 (2024년 2월)

- **폐지 일정**: 2024년 2월까지 순차 종료
  - 파일 첨부 API → 글 관련 API → 댓글 API → 기타 기능 순
- **폐지 사유**: AI 자동화 도구(ChatGPT 등)를 통한 대량 자동 포스팅으로 플랫폼 품질 저하
- **현재 상태**: 모든 API 엔드포인트 비활성화. 새 앱 등록 불가.
- **공식 안내**: https://tistory.github.io/document-tistory-apis/

### 구 API 스펙 (참고용)
- 글 작성: `POST /apis/post/write` (access_token, blogName, title, content, visibility, category, tag)
- 글 수정: `POST /apis/post/modify`
- 파일 첨부: `POST /apis/post/attach`
- 인증: 카카오 OAuth2 기반 access_token 발급

---

## 2. 카카오 OAuth 토큰 발급 방식

### 2-1. 토큰 유효 기간
- **Access Token**: 6시간 (REST API), 12시간 (JavaScript)
- **Refresh Token**: 2개월
  - 만료 1개월 이내 시점에 갱신 요청하면 새 refresh token 함께 발급
  - 주기적 갱신으로 무기한 유지 가능

### 2-2. 갱신 방법
```
POST https://kauth.kakao.com/oauth/token
grant_type=refresh_token
client_id={REST_API_KEY}
refresh_token={REFRESH_TOKEN}
client_secret={CLIENT_SECRET}  # 필수 (2024년부터 기본 활성화)
```

### 2-3. 자동 갱신 전략
- 크론잡으로 매주 1회 refresh token 갱신 실행
- 갱신된 토큰을 안전하게 저장 (파일 또는 DB)
- 만료 30일 전부터 갱신 가능하므로 여유 있게 관리

### 한계
- **카카오 OAuth 토큰으로 티스토리 API를 호출할 수 없음** (API 폐지됨)
- 카카오 OAuth는 카카오 로그인용으로만 유효
- 티스토리 자체 access_token은 더 이상 발급 불가

---

## 3. 2FA/OTP 우회 가능 방법 리서치

### 3-1. 카카오 앱 비밀번호 (App Password)
- **결론: 존재하지 않음**
- 카카오는 Google 스타일의 App-specific Password를 제공하지 않음
- 2FA는 카카오톡 앱 인증 또는 SMS OTP만 지원

### 3-2. OAuth Refresh Token 장기 유지
- 위 섹션 2-2 참조
- **한계**: 티스토리 API가 폐지되어 토큰이 있어도 API 호출 불가

### 3-3. 쿠키/세션 기반 인증 유지
- **가능성: 높음 (채택)**
- 카카오 로그인 후 티스토리가 발급하는 세션 쿠키를 저장하면 재로그인 없이 접근 가능
- 세션 유효기간: 수일~수주 (정확한 만료는 비공개)
- 구현: Playwright `storage_state` API로 쿠키+localStorage 일괄 저장/복원

### 3-4. Playwright 브라우저 자동화 (최초 1회 수동 → 세션 재사용)
- **결론: 최적 방법 (채택)**

**워크플로우:**
1. 최초 1회: Playwright 브라우저 열기 → 카카오 로그인 페이지 → 수동 로그인 (2FA 포함)
2. 로그인 완료 후: `context.storage_state(path="session.json")` 으로 세션 저장
3. 이후 실행: `browser.new_context(storage_state="session.json")` 으로 세션 복원
4. 세션 만료 시: 다시 수동 로그인 (자동 감지 → 프롬프트)

---

## 4. 추천 구현 방식

### 최종 선택: Playwright + Storage State

| 항목 | 내용 |
|------|------|
| 도구 | Playwright (Python) |
| 인증 | 최초 수동 로그인 → storage_state 저장 → 재사용 |
| 글 작성 | `https://{blog}.tistory.com/manage/newpost/` 페이지 조작 |
| 에디터 | HTML 모드로 전환 후 본문 입력 |
| 발행 | 비공개(private) 모드로만 발행 (PoC 단계) |
| 세션 만료 | 자동 감지 → 재로그인 안내 |

### 장점
- API 폐지와 무관하게 동작
- 2FA를 최초 1회만 통과하면 됨
- storage_state가 쿠키+localStorage를 포함하므로 안정적

### 단점/리스크
- UI 변경 시 셀렉터 업데이트 필요
- 세션 만료 주기가 비공개 (수일~수주)
- headless 모드에서 카카오 봇 감지 가능성 (최초 로그인은 headed 권장)
- 티스토리 하루 발행 제한: 블로그당 5건, 계정당 15건

### 대안 (검토 후 기각)
1. **제3자 API 서비스 (BridgeFlow 등)**: 월 비용 발생, 의존성 높음
2. **Selenium**: Playwright 대비 느리고, auto-wait 미지원
3. **카카오 OAuth + 구 API**: API 폐지로 불가

---

## 5. 환경 설정 필요사항

### .env.keys에 추가 필요
```bash
# 티스토리 자동 발행 설정
export TISTORY_BLOG_NAME="your-blog-name"          # 블로그 주소의 서브도메인
export TISTORY_SESSION_PATH="/home/jay/workspace/scripts/blog/.tistory_session.json"
export TISTORY_DEFAULT_CATEGORY="0"                 # 기본 카테고리 ID (0=분류없음)
```

### 카카오 로그인 정보
- `.env.keys`에 저장하지 않음 (2FA로 인해 자동 로그인 불가)
- 대신 Playwright storage_state JSON 파일로 세션 관리

---

## 6. 참고 자료

- 티스토리 API 종료 안내: https://tistory.github.io/document-tistory-apis/
- 카카오 OAuth REST API: https://developers.kakao.com/docs/latest/ko/kakaologin/rest-api
- Playwright Authentication: https://playwright.dev/docs/auth
- Playwright Python Cookie 관리: https://www.browserstack.com/guide/playwright-cookies