KappS 지식 베이스 · 블로그

2026년 App Store Connect API: 키, JWT 토큰, 속도 제한에 대한 단계별 가이드

블로그 가이드

App Store Connect API는 App Store Connect 웹 인터페이스 뒤에서 동작하는 REST 계층입니다. Apple의 설명에 따르면 이 API는 "App Store Connect에서 수행하는 작업을 자동화"할 수 있게 해주며, 이를 통해 변경한 사항은 프로덕션 데이터라는 점을 분명히 경고합니다. 이 안내서가 존재하는 이유가 바로 이 한 문장입니다. 유효한 키와 토큰만 있으면 브라우저 없이도 사용자를 초대하고, 번들 ID를 변경하고, 빌드를 업로드하고, App Store 메타데이터를 편집하고, 판매 보고서를 내려받을 수 있습니다. 이 2026년 안내서는 계정 소유자만 제출할 수 있는 액세스 요청, 팀 키와 개인 키의 차이, 모든 호출을 인증하는 ES256 JWT, 롤링 1시간 기준 요청 한도와 HTTP 429, 오류 해석, 페이지 처리, 소재 업로드, 키 폐기까지 다룹니다.

한 줄 요약: 계정 소유자가 API 액세스를 한 번 요청하고, 관리자가 역할 범위가 지정된 팀 키를 생성하거나(또는 각 사용자가 개별 키를 생성하거나) 하면, 코드가 kid가 키 ID이고 aud가 appstoreconnect-v1인 단기 ES256 JWT에 서명합니다. 모든 응답에는 X-Rate-Limit 헤더가 포함되며, 시간당 한도를 초과하면 429 RATE_LIMIT_EXCEEDED가 반환됩니다.

1단계 — API가 실제로 닿는 범위 파악하기

무엇이든 요청하기 전에 자동화하려는 범위를 먼저 파악하세요. 키의 역할에 따라 접근 가능한 리소스가 달라지기 때문입니다. Apple는 인앱 결제와 자동 갱신 구독, TestFlight 베타 빌드·테스터·그룹, Xcode Cloud 데이터와 워크플로, 사용자 및 접근 권한, 프로비저닝(번들 ID, 기능, 인증서, 기기, 프로파일), 앱 Meta데이터와 제출, App Clip 경험, 리포트(판매 및 재무 리포트), 전력 및 성능 지표, 고객 리뷰와 답변에 대한 리소스를 문서화합니다. 두 가지 구조적 사실이 중요합니다. 리소스는 리소스 간 탐색을 위한 관계 링크가 포함된 일관된 JSON을 반환하며, 계정이 Apple Developer Enterprise Program에 속해 있다면 Apple는 이 API 대신 Enterprise Program API를 안내합니다. 잘못된 API로 개발을 진행했다가 출시 과정에서 발견하는 일이 없어야 합니다.

2단계 — 계정 보유자만 요청할 수 있는 접근 권한 신청

API 액세스는 기본적으로 활성화되지 않으며 키별 토글이 아닙니다. 계정 소유자가 로그인하여 사용자 및 액세스 > 연동을 엽니다(페이지는 App Store Connect API가 선택된 상태로 열립니다). 액세스 요청을 클릭하고 약관에 동의한 후 제출합니다. 그러면 Apple이 요청을 검토하고 "사례별로" 승인합니다. 즉, 누군가에게 자동화 일정을 약속하기 전에 이 신청을 제출해야 하며, 릴리스 당일에 제출해서는 안 됩니다. 승인되면 같은 페이지에서 발급자 ID와 키 목록을 확인할 수 있습니다.

3단계 — 팀 키 또는 개인 키를 올바르게 선택하세요

Apple는 두 가지 키 유형을 정의하며, 이 둘은 서로 호환되지 않습니다:

  • 팀 키 — 계정 소유자나 관리자가 생성하며 계정 내 모든 앱에 적용되고, 선택한 역할에 따라 액세스 권한이 설정됩니다. 팀 키를 특정 앱으로 제한할 수는 없습니다. "팀 API 키는 모든 앱에 적용되므로 API 키에 대해 앱 액세스를 제한할 수 없습니다."
  • 개별 키 — 사용자가 프로필에서 생성하며, 해당 사용자의 앱과 역할이 적용됩니다. 생성할 수 있는 역할은 계정 소유자, 관리자, 앱 관리자, 고객 지원, 개발자, 마케팅이며, 각 사용자는 한 번에 하나의 활성 키만 보유할 수 있습니다. Apple 문서에는 설계 시 고려해야 할 두 가지 엄격한 제한이 추가로 명시되어 있습니다. 개별 키는 프로비저닝 엔드포인트나 notaryTool을 사용할 수 없습니다.

여기서 운영상 두 가지 규칙이 따릅니다. 키의 이름과 액세스 수준은 생성 후 수정할 수 없습니다. 둘 중 하나를 변경하려면 키를 폐기하고 새로 생성해야 합니다. 또한 비공개 키 부분은 단 한 번만 다운로드할 수 있습니다. 파이프라인에서 이를 잃어버렸다면 재다운로드가 아니라 새 키를 발급해야 합니다. 서버 측 비밀 저장소를 두고 .p8 파일을 데이터베이스 비밀번호처럼 취급하세요.

4단계 — Apple가 실제로 허용하는 ES256 토큰 생성하기

모든 요청에는 다운로드한 개인 키로 서명한 JWT가 필요합니다. Apple의 토큰 문서는 헤더 필드를 명확히 규정합니다. alg는 ES256이어야 하고, kid는 개인 키 ID(예: 2X9R4HXF34)이며, typ는 JWT입니다. 팀 키의 경우 페이로드에는 iss(발급자 ID, 예: 57246542-96fe-1a63-e053-0824d011072a), UNIX 에포크 시간 기준의 iat와 exp, 그리고 appstoreconnect-v1로 설정된 aud가 포함됩니다. 운영 환경에서 문제가 되는 것은 만료 규칙입니다. 만료 시각이 현재로부터 20분을 초과하는 토큰은 유효하지 않습니다. 단, Apple이 예외로 명시한 리소스는 제외됩니다. 짧은 토큰을 발급하고, 유효 시간 내에서 재사용하며, 그 시간이 지난 토큰을 절대 캐시하지 마세요. 팀 키가 여러 개인 경우 kid는 토큰에 서명한 개인 키와 동일한 키에 속해야 합니다. 짝이 맞지 않으면 인증 단계에서 실패하며, 권한 부여 문제가 아닙니다.

개인 키는 페이로드가 조금 다릅니다. iss가 없고, 대신 값이 user인 sub 클레임이 들어갑니다. 두 키 유형 모두에 쓸 토큰 빌더를 작성한다면, 이 차이를 런타임에 추론하지 말고 코드에서 명시하세요.

5단계 — 유출되지 않기를 바라지 말고 토큰 범위를 설정하세요

Apple은 선택적 scope 클레임을 지원합니다. 이는 해당 토큰이 수행할 수 있는 요청 목록으로, 각 항목은 HTTP 메서드, URL 경로, 선택적 쿼리 문자열로 구성됩니다. 예를 들어 GET /v1/apps/123 또는 GET /v1/apps?filter[platform]=IOS입니다. 요청을 포함하지 않는 범위로 제출된 토큰은 거부됩니다. Apple이 제시하는 근거는 범위 설정이 과하다고 주장하는 사람에게 그대로 인용할 만합니다. 실수로 권한이 없는 제3자와 토큰을 공유하더라도 제한된 범위는 해당 제3자가 할 수 있는 일을 줄여줍니다. 판매 보고서만 읽는 자동화에는 키 역할의 전체 권한이 아니라 읽기 전용 범위를 부여해야 합니다.

6단계 — 롤링 1시간 한도를 준수하고 429를 오류가 아닌 상태로 처리하세요

이 API의 속도 제한은 키 단위로 적용되며, 하나의 고정된 수치로 문서화되어 있지 않습니다. 모든 응답에는 X-Rate-Limit 헤더가 포함되며, 여기에는 user-hour-lim(해당 키에 대해 시간당 허용되는 요청 수)과 user-hour-rem(남은 요청 수)이 담깁니다. Apple의 예시 자체가 시간당 3,500건 한도에 500건이 남은 경우를 보여 주면서, 실제 한도는 달라질 수 있다고 명시합니다. 기준 구간은 롤링 1시간입니다. 즉 어느 시점이든 남은 요청 수는 한도에서 직전 60분 동안 보낸 모든 요청을 뺀 값입니다. 한도를 초과하면 API는 HTTP 429와 RATE_LIMIT_EXCEEDED 오류 코드로 응답합니다. 설계에 두 가지 함의가 있습니다. user-hour-rem을 읽어 값이 낮을 때 선제적으로 스로틀링하고, 429는 치명적 오류가 아니라 "기록해 두고 작업을 나중으로 큐잉"할 대상으로 다뤄야 합니다. 429에서 요란하게 실패하는 야간 내보내기 작업은 한도에 근접하는 날마다 매번 실패하게 됩니다.

7단계 — 상태 코드에서 실패를 읽은 다음 오류 객체를 확인하세요

Apple의 오류 가이드에 따르면, 200대 상태 코드는 성공을 의미하며 본문에 데이터가 담깁니다. 400대 또는 500대 코드는 요청 실패를 의미하며 본문에 상세 내용이 담깁니다. 오류 객체에는 프로그래밍 방식 처리를 위한 code도 포함되며, 대부분의 경우 요청에서 정확히 무엇이 잘못되었는지를 가리키는 source 객체도 함께 제공됩니다. 이는 페이로드 내부를 가리키는 JSON 포인터이거나 오류를 발생시킨 쿼리 매개변수입니다. 요청을 다시 작성하기 전에 source를 먼저 확인하세요. "내 JSON이 이 경로에서 형식 오류다"와 "내 역할로는 이 작업을 할 수 없다"의 차이는 5분짜리 수정과 지원 티켓의 차이입니다.

8단계 — 더 큰 한도를 추측하지 말고 대용량 결과 집합을 페이지로 나누세요

컬렉션 응답에는 페이징 정보와 관련 링크가 포함됩니다. 즉 페이지네이션 객체와 다음 페이지로 넘어가는 응답 링크입니다. 커서가 소진될 때까지 이 링크를 따라가는 루프를 작성하세요. 한 번의 호출로 모든 빌드, 테스터, App Store 버전이 반환된다고 가정하지 말고, "충분히 클 것"이라고 생각하는 페이지 크기를 하드코딩하지 마세요. 조용히 잘린 보고서는 느린 보고서보다 나쁩니다.

9단계 — Apple가 요구하는 순서대로 소재를 업로드하세요

바이너리 에셋, 즉 스크린샷, 앱 미리보기, 앱 심사용 첨부 파일, 라우팅 앱 커버리지 파일은 4단계 흐름을 따릅니다. 에셋 예약(에셋 유형, 파일 이름, 바이트 단위 크기)을 생성하고, 해당 응답에서 반환된 작업을 사용해 바이트를 업로드하고, 업로드를 커밋한 다음, App Store Connect가 에셋을 처리했는지 확인합니다. 예약에 성공하면 예약 ID, 업로드 작업 집합, 파일 속성, 그리고 AWAITING_UPLOAD 상태의 전달 상태가 반환됩니다. 대용량 파일은 각 부분의 오프셋과 길이를 알려주는 여러 작업으로 나뉘어 반환됩니다. 연결이 불안정해도 파일 전체를 잃지 않도록 API가 의도적으로 분할하는 것입니다. 또한 앱 스크린샷, 앱 미리보기, 인앱 이벤트 스크린샷 리소스는 지원이 종료되었습니다. 스크린샷, 미리보기, 인앱 이벤트 미디어는 대신 App Asset Library와 배치를 통해 관리하세요. 예약을 미완료 상태로 남겨두지 마세요. Apple에 따르면 예약 후 업로드를 완료할 수 있는 시간이 제한되어 있습니다.

10단계 — 키를 자격 증명처럼 교체하고 폐기하기

계정 소유자 또는 관리자는팀 키와 팀 구성원의 개별 키를폐기할 수 있으며, 사용자는 자신의 키를 직접 폐기할 수 있습니다. 폐기는 즉시 적용되고영구적입니다— 폐기된 키는 복구할 수 없으므로, 폐기는 최후의 수단이 아니라 올바른 긴급 조치입니다. 폐기된 키는 API 키 페이지의 폐기됨 항목 아래에30일 동안표시되는데, 이는 사고 발생 후 "어떤 키였지?"라는 질문에 답하기에는 충분하지만 감사 기록으로 삼기에는 부족한 기간이므로 자동화 실행 내역과 함께 키 ID를 기록해 두세요. 마지막으로, 특정 사용자에게 API 액세스 권한 자체를 부여해서는 안 되는 경우 관리자는개별 API 키 생성권한을 해당 사용자에게서 제거할 수 있습니다. 위치는사용자메뉴이며, 이런 제어 기능이 있으니 정책에만 의존하지 말고 활용하세요.

%%META_DESC%%

  • 계정 소유자가 접근 요청을 제출했고 승인되었습니다.
  • 키 유형을 의도적으로 선택: 계정 전체 자동화에는 팀 키, 특정 사용자 범위에는 개별 키.
  • 개인 키는 시크릿 매니저에 한 번만 저장하고, 관리 책임자를 문서화합니다.
  • 토큰 빌더: ES256, 서명 키와 일치하는 kid, aud=appstoreconnect-v1, exp는 20분 이내, scope는 작업에 필요한 만큼만 최소로.
  • 클라이언트가 X-Rate-Limit을 읽고 한도 전에 백오프하며 429에서 대기열에 넣습니다.
  • 수집 호출은 페이징 링크를 따릅니다. 첫 페이지가 완전하다고 가정하지 않습니다.
  • 에셋 업로드 예약, 파트, 커밋, 검증 상태를 확인했습니다.
  • 해지된 키는 사유와 날짜와 함께 기록됨; 30일 노출은 감사 로그로 간주되지 않음.

Apple는 API에 대한 출시 노트 변경 이력을 유지합니다. Apple는 시간이 지나면서 필드와 리소스를 추가하므로, 연동을 완료했다고 판단하기 전에 다시 읽어보세요.

출처

개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.

클릭하여 파일 선택 · 우클릭 → 붙여넣기, 또는 Ctrl/⌘+V로 스크린샷 붙여넣기

파일을 이 상자로 끌어다 놓아도 됩니다.

입력하신 이메일로 답변드립니다. 고객님의 정보는 KappS에만 보관됩니다.

✔ 제출 완료

메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.


← 수정으로 돌아가기