# Meta Threads API 세팅 가이드

**작성일**: 2026-03-13
**작성**: 아누 (개발실장)
**참고 출처**: mkt.chef.ai 스레드 글 + Meta 공식 문서 + ThreadAuto 실전 경험
**용도**: InsuRo 고객 가이드 기초자료 / 내부 세팅 매뉴얼

---

## 목차

1. 사전 준비물
2. Meta 개발자 포털 가입
3. 앱 만들기 (Threads API 용도 선택)
4. 권한(Scope) 설정
5. Threads 테스터 등록
6. 토큰 발급 (3단계)
7. 토큰 갱신 (60일 주기)
8. 트러블슈팅 (자주 겪는 문제)
9. InsuRo 서비스 연동 시 추가 고려사항

---

## 1. 사전 준비물

| 항목 | 설명 | 비고 |
|------|------|------|
| Threads 계정 | 게시할 Threads 계정 (공개 프로필 필수) | 비공개 프로필은 토큰 갱신 불가 |
| Facebook 계정 | Meta 개발자 포털 로그인용 | Threads 계정과 동일인 권장 |
| 서버/콜백 URL | OAuth 코드를 받을 HTTPS 주소 | `http://localhost`도 개발 중 사용 가능 |

**⚠️ 핵심 주의사항**:
- Threads 계정이 **공개(Public)** 상태여야 함. 비공개 시 토큰 권한이 90일 후 만료되며 갱신 불가
- Facebook 계정에 **2단계 인증** 활성화 권장 (앱 심사 시 필수)

---

## 2. Meta 개발자 포털 가입

### 2-1. 접속
- URL: **https://developers.facebook.com**
- Facebook 계정으로 로그인

### 2-2. 개발자 등록
- 첫 접속 시 "Get Started" 클릭
- 이메일 인증 완료
- 개발자 정책 동의

### 2-3. 본인 확인 (App Review 시 필요)
- **개인 개발자**: 여권, 주민등록증, 운전면허증 중 택1 업로드
- **사업자**: 사업자등록증 + 대표자 신분증
- ⚠️ 앱 심사(App Review) 전까지는 본인 확인 불필요. 테스터 모드로 먼저 사용 가능

---

## 3. 앱 만들기

### 3-1. 앱 생성
1. **developers.facebook.com** → "내 앱(My Apps)" 클릭
2. **"앱 만들기(Create App)"** 클릭
3. 앱 이름 입력 (예: "인슈로 ThreadAuto", "내 보험 마케팅")
4. 연락처 이메일 입력

### 3-2. Use Case 선택 ← ★ 가장 중요한 단계

> ⚠️ mkt.chef.ai 스레드 글 핵심 경고:
> **"이 단계에서 체크한 항목이 API 범위를 결정해요. 나중에 변경 어려워요."**

**Threads API만 필요한 경우** (InsuRo 고객 기본):
- Use Case → **"기타(Other)"** 또는 **"콘텐츠 관리(Access the Threads API)"** 선택
- Threads API 체크 ✅

**광고 자동화도 필요한 경우** (mkt.chef.ai 글의 케이스):
- Use Case → **"광고 자동화(Advertising or Monetization)"** 선택
- Marketing API 3개 모두 체크 ✅
- ⚠️ InsuRo 고객은 이거 필요 없음. Threads 게시만 하면 됨

### 3-3. 커스터마이징 완료
- 앱 대시보드에서 **"Finish customization"** 클릭
- **"Yes I'm finished"** 선택
- ⚠️ 이 단계를 빠뜨리면 API가 작동하지 않을 수 있음

---

## 4. 권한(Scope) 설정

### 4-1. Threads API 권한 종류

| 권한 | 설명 | InsuRo 필수? |
|------|------|:---:|
| `threads_basic` | 프로필/게시글 조회 | ✅ 필수 |
| `threads_content_publish` | 게시글 발행 | ✅ 필수 |
| `threads_manage_replies` | 댓글 관리 (숨기기, 답글) | 선택 |
| `threads_read_replies` | 댓글 조회 | 선택 |
| `threads_manage_insights` | 분석 지표 (조회수, 좋아요 등) | 권장 |

**InsuRo 최소 세트**: `threads_basic,threads_content_publish`
**InsuRo 권장 세트**: `threads_basic,threads_content_publish,threads_manage_insights`

### 4-2. 권한 추가 방법
1. 앱 대시보드 → **"Use cases"** 메뉴
2. **"Customize"** 클릭
3. 필요한 권한 추가 (Add)

### 4-3. 광고 API 권한 (mkt.chef.ai 글 참고, InsuRo에는 불필요)

mkt.chef.ai 글에서 언급한 3개 권한:
- `ads_management` — 광고 생성/수정/삭제
- `ads_read` — 광고 성과 조회
- `business_management` — 비즈니스 관리자 연동

> mkt.chef.ai 경고: **"셋 다 있어야 해요. 하나라도 빠지면 에러 나요."**
> → 이 경고는 광고 API에 해당. Threads API 사용자는 해당 없음

---

## 5. Threads 테스터 등록

### 5-1. 왜 필요한가?
- 앱 심사(App Review) 통과 전에는 **테스터로 등록된 사용자만** API 사용 가능
- 개발/테스트 단계에서 필수

### 5-2. 테스터 추가 방법 (개발자가 하는 작업)
1. 앱 대시보드 → **"App roles"** → **"Roles"** 탭
2. **"Add People"** 클릭
3. "Additional Roles for this App" → **"Threads Tester"** 선택
4. Threads 사용자 이름(username) 입력

### 5-3. 테스터 초대 수락 (Threads 계정 소유자가 하는 작업)
1. Threads 앱 → **설정(Settings)** 진입
2. **계정(Account)** → **웹사이트 권한(Website Permissions)** 탭
3. 대기 중인 초대 확인 → **수락(Accept)**

⚠️ **제이회장님 실전 경험 기반 주의사항**:
- 이 수락 과정이 직관적이지 않음. "설정 > 계정 > 웹사이트 권한"을 찾기 어려움
- 초대가 안 보이면: Threads 앱 업데이트 후 재시도
- **InsuRo 가이드에서 이 부분을 스크린샷 포함 상세 안내 필수**

---

## 6. 토큰 발급 (3단계)

### 6-0. 필요한 정보 미리 확인
앱 대시보드 → **App Settings** → **Basic**:
- **Threads App ID** (= App ID)
- **Threads App Secret** (= App Secret) ← "Show" 클릭해서 확인

앱 대시보드 → **Use cases** → **Customize** → **Settings**:
- **Redirect URI** 등록 (OAuth 코드를 받을 URL)

### 6-1. Step 1: 인증 코드 요청 (브라우저)

사용자를 아래 URL로 리다이렉트:

```
https://threads.net/oauth/authorize
  ?client_id={THREADS_APP_ID}
  &redirect_uri={REDIRECT_URI}
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code
  &state={CSRF_방지_랜덤값}
```

**결과**: 사용자가 권한 승인 → `{REDIRECT_URI}?code={인증코드}&state={상태값}` 으로 리다이렉트

- 인증 코드 유효기간: **1시간**
- 1회 사용 후 폐기됨

### 6-2. Step 2: 단기 액세스 토큰 발급

```
POST https://graph.threads.net/oauth/access_token

Body (form-data):
  client_id={THREADS_APP_ID}
  client_secret={THREADS_APP_SECRET}
  grant_type=authorization_code
  redirect_uri={REDIRECT_URI}  ← Step 1과 정확히 동일해야 함
  code={인증코드}
```

**성공 응답**:
```json
{
  "access_token": "THQVJ...",
  "user_id": 17841405793187218
}
```

- 단기 토큰 유효기간: **1시간**
- ⚠️ redirect_uri가 Step 1과 **한 글자라도** 다르면 에러

### 6-3. Step 3: 장기 액세스 토큰 교환

```
GET https://graph.threads.net/access_token
  ?grant_type=th_exchange_token
  &client_secret={THREADS_APP_SECRET}
  &access_token={단기_토큰}
```

**성공 응답**:
```json
{
  "access_token": "THQVJ...장기토큰...",
  "token_type": "bearer",
  "expires_in": 5184000
}
```

- 장기 토큰 유효기간: **60일** (5,184,000초)
- ⚠️ 이 토큰을 안전하게 저장해야 함 (DB 암호화 권장)

---

## 7. 토큰 갱신 (60일 주기)

### 7-1. 갱신 엔드포인트

```
GET https://graph.threads.net/refresh_access_token
  ?grant_type=th_refresh_token
  &access_token={현재_장기토큰}
```

**성공 응답**:
```json
{
  "access_token": "THQVJ...새_장기토큰...",
  "token_type": "bearer",
  "expires_in": 5184000
}
```

### 7-2. 갱신 규칙

- 만료 **1일 전**부터 갱신 가능 (ThreadAuto 구현: 만료 7일 전 자동 갱신)
- 갱신하면 기존 토큰 무효화, 새 토큰 발급
- **공개 프로필**: 갱신 시 권한도 90일 연장
- **비공개 프로필**: 갱신 불가 → 처음부터 다시 인증 필요 (사용 금지 사유)

### 7-3. 자동 갱신 구현 포인트 (InsuRo 서비스)
- 토큰 저장 시 `expires_at` (만료 일시) 함께 저장
- 매일 1회 크론잡으로 만료 7일 이내 토큰 자동 갱신
- 갱신 실패 시 사용자에게 알림 (재인증 안내)

---

## 8. 트러블슈팅 (자주 겪는 문제)

### 8-1. "Invalid redirect_uri" 에러
**원인**: Step 1의 redirect_uri와 Step 2의 redirect_uri가 다름
**해결**: URL이 정확히 동일한지 확인 (후행 슬래시 `/` 포함)

### 8-2. "This authorization code has been used" 에러
**원인**: 인증 코드를 2번 사용
**해결**: 코드는 1회용. 실패 시 처음(Step 1)부터 다시

### 8-3. 테스터 초대가 안 보임
**원인**: Threads 앱 버전 오래됨 / 캐시
**해결**: 앱 업데이트 → 설정 > 계정 > 웹사이트 권한 다시 확인

### 8-4. "Unsupported get request" 에러
**원인**: `threads_basic` 권한 누락 또는 앱 커스터마이징 미완료
**해결**: 앱 대시보드에서 "Finish customization" 완료 확인

### 8-5. 이미지 게시 시 "Media URL is not reachable" 에러
**원인**: 이미지가 공개 HTTPS URL이 아님
**해결**: 이미지를 공개 서버(GCS/S3/CDN)에 업로드 후 해당 URL 사용

### 8-6. 토큰이 갑자기 무효화됨
**원인**:
- (1) 사용자가 비밀번호 변경
- (2) 사용자가 앱 권한 철회
- (3) 60일 만료
**해결**: 사용자에게 재인증 안내

### 8-7. 자산(Asset) 연결 누락 (mkt.chef.ai 글 참고 — 광고 API 전용)

> mkt.chef.ai 경고: **"이 단계 빠뜨리면 토큰 있어도 광고 계정 접근이 안 돼요."**

- Business Manager → 설정 → 사용자 → 시스템 사용자 → 자산 추가
- 광고 계정 + 픽셀에 "전체 액세스" 할당
- ⚠️ **Threads API에는 해당 없음.** 이 단계는 Marketing API(광고 자동화)에만 필요

---

## 9. InsuRo 서비스 연동 시 추가 고려사항

### 9-1. 고객 세팅 가이드 설계 방향

**제이회장님 확정 방침** (2026-03-13):
> "원스탑 연결은 불가능. 세팅하는데 AI가 직접 못해서 하나하나 사용자가 직접 해야 함."

따라서:
- ~~OAuth 원클릭 셋업~~ → **스크린샷 기반 5단계 위저드**가 핵심
- InsuRo 앱 내에서 각 단계를 번호 매기고 스크린샷과 함께 안내
- 각 단계마다 "이 화면이 보이시나요?" 체크포인트
- Meta 개발자 포털 용어를 보험설계사 친화적으로 치환

### 9-2. 용어 치환표 (보험설계사 눈높이)

| Meta 원래 용어 | InsuRo 안내 용어 |
|---|---|
| Developer Portal | Threads 연결센터 |
| App | 내 마케팅 앱 |
| Access Token | 연결 키 |
| App Secret | 비밀 키 |
| Redirect URI | 연결 주소 |
| Scope / Permissions | 사용 권한 |
| OAuth | 계정 연결 |
| Threads Tester | 테스트 사용자 |
| App Review | 앱 검수 |

### 9-3. InsuRo 메뉴 구조

**좌측 메뉴 트리**:
```
📋 AI 콘텐츠 작성
  └─ 채널 선택
      ├─ Threads
      │   └─ 텍스트/카드뉴스/영상 작성
      ├─ Instagram (향후)
      └─ 네이버블로그 (향후)

🤖 AI 포스팅 자동화       ← 별도 메뉴 (향후 개발)
  └─ 스케줄 설정
  └─ 자동 발행 관리
```

**콘텐츠 생성하기 화면** (채널 > Threads 진입 후):
- **텍스트 작성**: 텍스트 전용 게시글 생성 (AI 초안 → 편집 → 발행)
- **이미지 작성**: 카드뉴스/이미지 게시글 생성 (템플릿 선택 → AI 내용 생성 → 발행)
- **영상 작성**: 숏폼 영상 게시글 생성 (스크립트 → 영상 렌더링 → 발행)

3가지 중 택1 → 각 모드별 에디터 진입

### 9-4. InsuRo 세팅 위저드 단계 구성안

**1단계 — Meta 개발자 등록** (1회만)
- developers.facebook.com 접속 → Facebook 로그인 → 개발자 등록
- 예상 소요: 2~3분

**2단계 — 앱 만들기** (1회만)
- "앱 만들기" → 이름 입력 → "Threads API" 선택
- 커스터마이징 완료 클릭
- 예상 소요: 3~5분

**3단계 — 내 Threads 계정 연결** (1회만)
- App roles → Threads Tester 추가 (본인 username)
- Threads 앱에서 초대 수락
- 예상 소요: 2~3분 (초대 도착까지 최대 5분 대기)

**4단계 — 연결 키(토큰) 발급** (1회만, InsuRo가 자동 처리)
- InsuRo "연결하기" 버튼 클릭
- Threads 로그인 → 권한 승인
- InsuRo가 자동으로 토큰 교환 & 저장
- 예상 소요: 1분

**5단계 — 연결 확인**
- InsuRo에서 "테스트 게시" 버튼 클릭
- Threads에 테스트 글 올라가는지 확인
- 예상 소요: 30초

**총 예상 소요: 10~15분** (1~3단계는 사용자 수동, 4~5단계는 InsuRo 반자동)

### 9-5. 토큰 보안 아키텍처

- 토큰은 AES-256-GCM으로 암호화 저장 (Supabase)
- RLS(Row Level Security)로 본인 토큰만 접근 가능
- 마스터 키: 환경변수/KMS (DB에 평문 저장 금지)
- 갱신 크론: 만료 7일 전 자동 갱신 시도

### 9-6. App Review (앱 심사) — 서비스 공개 시 필수

테스터 모드에서는 테스터 등록 사용자만 API 사용 가능.
**불특정 다수 InsuRo 고객이 사용하려면 앱 심사 통과 필수.**

- 심사 소요: 보통 **2~3일**, 최대 1주일
- 필요 서류: 앱 사용 목적 설명, 스크린샷, 데이터 처리 방침
- 각 권한(scope)별 개별 심사
- 본인 확인 서류 업로드 (여권/신분증)

---

## 참고 자료

- [Meta Threads API 공식 문서 — Get Started](https://developers.facebook.com/docs/threads/get-started/)
- [토큰 발급 공식 가이드](https://developers.facebook.com/docs/threads/get-started/get-access-tokens-and-permissions/)
- [mkt.chef.ai 스레드 글 — API 토큰 총정리](https://www.threads.com/@mkt.chef.ai/post/DV0audCD-MS)
- [App Review 제출 가이드](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review/submission-guide)
- ThreadAuto 기술 리서치: `memory/research/threadauto-tech-research.md`
- ThreadAuto OAuth 구현: `/home/jay/projects/ThreadAuto/auth/oauth.py`

---

## mkt.chef.ai 스레드 글 원문 요약 (보존)

**제목**: "메타 광고 자동화·에이전트에 붙일 API 토큰, 받는 순서 총정리했어요"

mkt.chef.ai 글은 **광고 자동화(Marketing API)** 기준으로 작성됨. Threads 게시 전용과 차이:

| 단계 | mkt.chef.ai (광고 API) | InsuRo (Threads API) |
|------|---|---|
| 1 | 개발자 포털 → 앱 만들기 | 동일 |
| 2 | 광고 자동화 Use Case 선택 | **Threads API** Use Case 선택 |
| 3 | Marketing API 3개 체크 | threads_basic + threads_content_publish 체크 |
| 4 | Business Manager 시스템 사용자 생성 | **불필요** (Threads는 OAuth 직접) |
| 5 | 시스템 사용자에 광고계정/픽셀 자산 연결 | **불필요** |
| 토큰 | 시스템 사용자 토큰 (비만료) | OAuth 토큰 (60일, 갱신 가능) |

**핵심 차이**: 광고 API는 Business Manager + 시스템 사용자가 필요하지만,
Threads API는 **OAuth만으로 충분**. 더 단순함.

단, mkt.chef.ai 글의 경고 3가지는 보편적으로 유효:
1. ✅ Use Case 선택 단계에서 체크 항목이 API 범위 결정 (나중에 변경 어려움)
2. ✅ 권한은 빠짐없이 체크 (하나라도 누락 시 에러)
3. ✅ 자산 연결 안 하면 토큰 있어도 접근 불가 → Threads는 해당 없지만 원리는 동일