App Store Connect API 401: 2026 JWT 어떻게 고치나요?

App Store Connect API 401이 발생했다면 키를 계속 폐기하고 다시 만들지 말고, 먼저 호출 API를 확인한 뒤 키 출처, JWT 필드와 시스템 시계, 역할 권한, 원격 맥의 비밀값 주입 순서로 점검해야 합니다. 최소 요청에서도 계속 401이 나오면 요청 ID를 포함해 Apple에 문의해야 합니다.

이 글은 다음 개발자를 위한 내용입니다.

• fastlane으로 TestFlight를 올리다가 API 키 인증이 갑자기 실패한 독립 개발자
• 작업을 원격 맥으로 옮긴 뒤 로컬 성공과 원격 401이 엇갈리는 유지 관리자
• 직접 JWT를 만들고 App Store Connect API를 호출하는 자동화 개발자

실패 증거부터 분리하기

첫 단계는 오류 문구를 고치는 일이 아니라, 실패한 요청의 정체를 고정하는 일입니다. 기록할 항목은 다음과 같습니다.

• 요청 주소와 HTTP 상태
• Apple이 반환한 오류 코드와 요청 ID
• 실행 도구와 작업 이름
• 로컬, SSH, CI 실행기 중 어느 입구에서 실패했는지
• TestFlight 전송인지, API 조회인지, 다른 자동화 작업인지

예를 들어 로컬 스크립트는 JWT를 만들고 최소 조회 요청에도 성공하지만, 원격 맥의 CI 실행기에서는 401을 반환한다고 가정하겠습니다. 이때 “JWT 생성 성공”은 키 파일을 읽고 서명할 수 있다는 뜻일 뿐입니다. Apple이 그 키를 현재 API와 작업에 사용할 수 있다고 승인했다는 뜻은 아닙니다.

Apple의 API 오류 응답 설명에서 상태와 오류 세부 정보를 대조하십시오. 요청 ID가 있다면 나중에 문의할 때 원인 범위를 좁히는 증거가 됩니다.

또한 App Store Connect API, App Store Server API, Transporter 업로드, fastlane 작업을 한 묶음으로 취급하면 안 됩니다. 같은 “업로드 실패”처럼 보여도 인증 주체와 요청 경로가 다를 수 있습니다.

키 출처와 API 경계

.p8 파일만으로 용도를 판단하지 않기

App Store Connect API 키와 인앱 결제 관련 키는 모두 개인 키 파일처럼 보일 수 있습니다. 그러나 같은 형식의 파일이라는 이유로 서로 교환할 수는 없습니다.

확인 순서는 다음과 같습니다.

• App Store Connect의 키 관리 화면에서 키가 생성된 위치를 확인합니다.
• Key ID를 파일 이름이 아니라 관리 화면과 대조합니다.
• Issuer ID가 해당 팀과 연결되어 있는지 확인합니다.
• 호출 주소가 실제 키의 용도와 일치하는지 확인합니다.
• 팀용 키인지 개인용 키인지, 그리고 목표 작업에 필요한 역할인지 확인합니다.

App Store Connect API 키 안내는 키 생성 위치와 사용 범위를 확인할 때 기준으로 삼을 수 있습니다. 파일을 새로 받는 것보다 관리 화면의 정보와 실제 실행 로그를 대조하는 편이 안전합니다.

권한 부족과 인증 실패 나누기

키가 유효해도 목표 리소스에 접근할 역할이 없으면 작업이 중단될 수 있습니다. 반대로 JWT가 잘못되어 Apple이 요청 주체를 확인하지 못하면 인증 단계에서 실패합니다. 두 문제를 모두 401로 추정해서 키만 반복 발급하면 원인을 가릴 수 있습니다.

역할 권한 설명에서 API 키에 부여된 역할과 실제 작업을 비교하십시오. 사용자의 팀 상태, 계약 상태, 앱 접근 범위도 함께 확인해야 합니다. 권한을 바꾸기 전에는 최소 권한으로 필요한 조회만 수행하는 편이 좋습니다.

JWT 입력값과 원격 시계

App Store Connect API의 JWT는 헤더, 페이로드, 서명 입력이 모두 맞아야 합니다. Apple 문서에 따라 알고리즘은 ES256이며, 헤더에는 Key ID가 들어가고 페이로드에는 Issuer ID, 대상 값, 발급 시각과 만료 시각이 사용됩니다. 세부 필드와 토큰 유효 시간은 JWT 생성 요구 사항과 함께 확인해야 합니다.

다음처럼 층을 나눠 보십시오.

• 헤더: alg가 ES256인지, kid가 관리 화면의 Key ID와 같은지 확인합니다.
• 페이로드: iss, aud, iat, exp가 Apple 요구 형식에 맞는지 확인합니다.
• 서명 입력: 사용한 .p8 개인 키가 kid에 연결된 키인지 확인합니다.
• 실행 시계: 로컬과 원격 맥의 시간이 신뢰할 수 있는 시간원과 맞는지 확인합니다.

토큰 디코더에서 페이로드가 읽힌다고 성공으로 판단하면 안 됩니다. 디코더는 구조를 보여줄 뿐, Apple이 해당 키를 승인하는지 확인하지 않습니다. 원격 맥이 절전 복귀, 스냅샷 복원, 수동 시간 변경을 거쳤다면 발급 시각과 만료 시각이 현재 시간과 어긋날 수 있습니다.

JWT를 로그에 그대로 남기지 마십시오. kid와 실행 시각만 부분적으로 기록하고, iss, 개인 키 내용, 전체 토큰은 가려야 합니다. 로그 수집 시스템에 토큰이 남아 있다면 원인 확인 뒤 노출 범위를 평가하고 필요한 조치를 취해야 합니다.

fastlane과 원격 맥의 비밀값 주입

fastlane은 설정 파일에 적힌 값이 아니라 실행 환경에서 실제로 읽은 값을 사용합니다. 따라서 로컬 셸에서 성공한 설정을 SSH나 CI에서도 그대로 사용할 수 있다고 가정하면 안 됩니다.

확인해야 할 입력은 다음과 같습니다.

• key_id
• issuer_id
• key_filepath
• key_content
• 환경 변수의 이름과 적용 범위
• 실행 시점의 작업 경로
• 줄바꿈이 보존된 개인 키 내용

특히 key_filepath는 대화형 터미널에서는 존재하지만 CI 실행기의 작업 디렉터리에서는 존재하지 않을 수 있습니다. key_content를 사용하는 경우에는 Base64 변환과 복원 과정에서 줄바꿈이 달라질 수 있습니다. 어느 방식이든 로그에는 값 자체가 아니라 “읽기 성공 여부와 파일 존재 여부”만 남겨야 합니다.

fastlane의 App Store Connect API 설정 문서를 기준으로 현재 lane이 어떤 입력 방식을 사용하는지 확인하십시오. API 인증용 개인 키, 코드 서명용 인증서와 프로비저닝 프로필, 전송용 로그인 정보는 서로 다른 비밀값입니다. 하나가 성공했다고 다른 단계도 정상이라는 뜻은 아닙니다.

복구 순서 체크리스트

다음 순서는 키를 불필요하게 폐기하지 않고 원인을 좁히기 위한 절차입니다.

• [ ] 실패한 요청 주소가 App Store Connect API인지 확인합니다.
• [ ] HTTP 상태, 오류 코드, 요청 ID, 실행 도구를 별도 기록으로 남깁니다.
• [ ] 키가 App Store Connect API용으로 생성되었는지 관리 화면에서 확인합니다.
• [ ] Key ID, Issuer ID, 개인 키의 연결이 맞는지 대조합니다.
• [ ] JWT의 alg, kid, iss, aud, iat, exp를 점검합니다.
• [ ] 원격 맥의 시계를 신뢰할 수 있는 시간원과 비교합니다.
• [ ] 키 역할과 대상 앱 접근 범위를 목표 작업과 비교합니다.
• [ ] 대화형 셸, SSH, CI 실행기에서 실제 입력 방식이 같은지 확인합니다.
• [ ] 토큰이나 .p8 파일이 로그, 저장소, 빌드 산출물에 들어가지 않았는지 찾습니다.
• [ ] 권한이 허용된 최소 조회 요청을 먼저 실행합니다.
• [ ] 최소 요청이 성공한 뒤 TestFlight 업로드를 실행합니다.
• [ ] 새 키 발급은 기존 키의 대체 검증이 끝난 뒤 결정합니다.

최소 요청이 계속 401이면 네트워크를 바꾸거나 키를 반복해서 만들기 전에 증거를 모으십시오. 실행 계정, 키 유형, 요청 주소, 요청 ID, 실패 시각, 사용한 fastlane 입력 방식을 가린 상태로 정리하면 Apple에 전달할 진단 자료가 됩니다.

자주 발생하는 인증 오해

JWT가 만들어지면 키가 정상이라는 오해가 가장 흔합니다. 서명 라이브러리가 파일을 읽었다는 것과 Apple이 요청을 승인했다는 것은 다른 단계입니다.

권한을 올리면 401이 사라진다는 오해도 위험합니다. 역할이 부족한 문제와 잘못된 kid, iss, aud, 시계 문제는 별도로 검증해야 합니다. 권한을 과도하게 부여하면 보안 범위만 넓어집니다.

업로드 재시도로 인증 문제가 해결된다는 오해도 피해야 합니다. TestFlight 업로드를 반복하기 전에 최소 조회 요청으로 인증 체인을 검증해야 합니다. 그래야 빌드, 서명, 전송, API 인증 중 어느 단계가 문제인지 분리할 수 있습니다.

원격 맥을 상시 배포기로 쓸지 판단하기

로컬 맥에서만 성공하고 원격 실행기에서 실패한다면, API 자체보다 실행 환경의 차이를 먼저 의심해야 합니다. SSH 세션의 환경 변수, CI의 작업 경로, 개인 키 파일 권한, 로그 보존 방식이 서로 다를 수 있기 때문입니다.

반대로 같은 최소 요청이 로컬과 원격에서 모두 실패한다면 계정, 키 출처, 역할, JWT 입력값을 우선 검토해야 합니다. 새 키를 폐기하고 다시 만드는 작업은 기존 자동화와의 대체 관계가 확인된 뒤에만 진행하십시오. 기존 키를 먼저 취소하면 현재 배포 파이프라인까지 함께 멈출 수 있습니다.

매번 개인 컴퓨터를 켜고 비밀값을 주입하는 방식은 실행 시점이 불규칙하고, 로그를 보존하기 어렵고, 시스템 시계나 작업 경로 차이를 재현하기도 어렵습니다. 반대로 직접 운영하는 맥 미니는 초기 구매 비용, 유지 보수, 전원과 네트워크 관리, 장기간의 유휴 비용을 감수해야 합니다.

지속적인 배포를 위해 원격 맥을 검토한다면 원격 맥 활용 사례에서 자신의 작업 방식과 맞는지 먼저 확인하십시오. 단기간에 인증 체인을 재현하는 목적이라면 주 단위 이용이 맞을 수 있고, 로그와 비밀값 주입을 보존하는 상시 TestFlight 배포기라면 월 단위 운영이 더 적합할 수 있습니다. 실제 업로드가 통과한 뒤에 KVMFLUX 이용 요금을 비교하는 순서가 안전합니다.

결국 App Store Connect API 401의 해결책은 키를 무작정 교체하는 것이 아닙니다. API 경계, 키 출처, JWT, 역할, 실행 환경을 분리하고 최소 요청과 실제 업로드를 차례로 통과시켜야 합니다. 현재 방식이 로컬 맥 의존, 수동 비밀값 주입, 불안정한 실행 시간이라는 세 가지 약점을 갖고 있다면, 검증된 원격 맥을 배포기로 유지하는 편이 반복 장애를 줄이는 선택입니다. KVMFLUX를 사용할 때도 먼저 테스트 환경에서 인증과 실제 업로드를 확인한 뒤, 임시 검증에는 주 단위로, 상시 자동화에는 월 단위로 결정하는 것이 합리적입니다.

자주 묻는 질문