SNS 연결 API

앙크에 연동된 SNS 계정(Instagram, Threads, Bluesky, Facebook Page, TikTok, YouTube)의 목록과 권한 상태를 조회하는 API입니다. 콘텐츠 발행 전 대상 connection_id를 확보하고 계정의 발행 권한이 정상인지 검증할 때 사용합니다.

📌 엔드포인트 목록

메서드	경로	설명	필요 스코프
`GET`	`/v1/brand/connections`	연동된 SNS 계정 목록 조회 (플랫폼 필터링 지원)	`connections:read` 또는 `*`
`GET`	`/v1/brand/connections/{connection_id}`	특정 SNS 연결의 상세 정보 및 실시간 권한 진단 조회	`connections:read` 또는 `*`

📋 SNS 연결 목록 조회 (`GET /v1/brand/connections`)

브랜드에 연결된 모든 SNS 계정을 조회합니다. sns_type 쿼리 파라미터로 특정 플랫폼만 필터링할 수 있습니다.

쿼리 파라미터

파라미터	타입	필수 여부	설명
`sns_type`	`string`	선택	`instagram`, `threads`, `bluesky`, `facebook_page`, `tiktok`, `youtube` 중 하나로 필터링

요청 예시

curl -X GET "https://api.ankk.app/v1/brand/connections?sns_type=instagram" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

응답 예시 (`200 OK`)

{
  "items": [
    {
      "id": "conn_01jm8x9k2example",
      "sns_type": "instagram",
      "platform": "meta.instagram",
      "display_name": "ACME Official",
      "username": "acme_official",
      "profile_image_url": "https://example.com/profiles/acme.jpg",
      "status": "connected",
      "created_at": "2026-08-01T10:00:00Z"
    }
  ]
}

🔍 SNS 연결 상세 조회 (`GET /v1/brand/connections/{connection_id}`)

특정 연결의 세부 정보와 함께 **실시간 발행 권한 인가 상태(Publish Authorization)**를 확인합니다.

요청 예시

curl -X GET "https://api.ankk.app/v1/brand/connections/conn_01jm8x9k2example" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

응답 예시 (`200 OK`)

{
  "id": "conn_01jm8x9k2example",
  "sns_type": "instagram",
  "platform": "meta.instagram",
  "display_name": "ACME Official",
  "username": "acme_official",
  "profile_image_url": "https://example.com/profiles/acme.jpg",
  "status": "connected",
  "created_at": "2026-08-01T10:00:00Z",
  "publish_authorization": {
    "status": "scope_authorized",
    "required_scopes": ["instagram_business_basic", "instagram_business_content_publish"],
    "missing_scopes": [],
    "retryable": false
  }
}

권한 인가 상태값 (`publish_authorization.status`)

상태값	의미 및 대처 방법
`scope_authorized`	정상 인가 완료. 즉시 콘텐츠 발행 가능.
`scope_permission_unverified`	권한 검증 대기 중. 발행 시도 가능하나 런타임 결과 확인 필요.
`scope_permission_missing`	필수 권한 누락. Web UI에서 재인증 필요.
`scope_review_disabled`	플랫폼 앱 검수 미통과 또는 개발자 모드 제약.
`unsupported`	해당 연결에서 지원하지 않는 오퍼레이션.

🔗 관련 문서