2026년 기준 Apple은 API 요청용 JWT의 유효 시간을 최대 20분으로 안내합니다. Apple의 토큰 생성 규칙과 API Key의 폐기 상태는 별개입니다. App Store Connect API Key가 폐기됐다면 되살릴 수 없으며, 새 키를 만들고 이전 키를 쓰는 자동화 설정을 전부 교체해야 합니다.
이 글은 fastlane으로 앱을 올리거나 TestFlight 작업을 관리하는 독립 개발자와 소규모 팀을 위한 복구 안내입니다.
특히 인증 오류 때문에 배포가 멈췄거나 원격 맥의 비밀 정보를 교체해야 하는 경우에 적합합니다.
인증 오류가 나면 먼저 어떤 단계에서 막혔는지 확인해야 하나요?
오류를 곧바로 키 폐기로 해석하지 말고, 토큰 생성·키 상태·권한·설정값을 분리해 확인해야 합니다. JWT가 만료됐거나 생성에 실패한 경우, 폐기된 API Key를 사용한 경우, Key ID와 p8 파일이 맞지 않는 경우는 원인과 조치가 다릅니다.
먼저 fastlane 실행 로그에서 실패한 작업과 인증 오류 내용을 확인합니다. 이때 로그 전체를 외부에 공유하지 마세요. 인증 정보나 계정 식별 정보가 포함될 수 있습니다. 그다음 현재 작업이 실제로 읽는 Key ID와 키 파일 경로를 확인합니다. 파일을 교체했더라도 실행 환경 변수가 예전 경로를 가리키면 이전 키가 계속 사용될 수 있습니다.
JWT는 API 요청에 사용하는 토큰입니다. 따라서 토큰을 새로 만들어 인증을 다시 시도하는 것과 폐기된 API Key를 새 키로 교체하는 것은 다른 조치입니다. fastlane의 API Key 설정 항목에는 키 식별 정보와 키 파일 또는 키 내용의 전달 방식이 설명되어 있습니다. 설정의 어느 값이 바뀌었는지부터 대조하면 불필요한 키 재발급을 줄일 수 있습니다.
| 확인 항목 | 확인할 내용 | 다음 조치 |
|---|---|---|
| JWT | 생성 실패인지, 토큰 만료인지 확인합니다. | 토큰 생성 설정과 실행 시점을 점검합니다. |
| API Key 상태 | App Store Connect에서 키가 폐기됐는지 확인합니다. | 폐기된 키라면 새 키를 발급합니다. |
| 키 짝 | Key ID와 p8 파일이 같은 키에 속하는지 확인합니다. | 동일한 새 키의 정보를 함께 반영합니다. |
| 역할 권한 | 해당 키가 필요한 앱과 작업에 접근할 수 있는지 확인합니다. | 작업에 필요한 권한을 검토합니다. |
| 설정 출처 | fastlane이 환경 변수, 파일, 비밀 저장소 중 어디서 값을 읽는지 확인합니다. | 실제 실행 경로의 값을 교체합니다. |
폐기된 키와 개인 키·팀 키는 어떻게 구분해야 하나요?
Apple의 안내에 따르면 폐기한 키는 다시 활성화할 수 없습니다. 기존 p8 파일을 재다운로드해 복구하는 것도 대안이 아닙니다. App Store Connect API 키 관리 안내에서 현재 키 상태와 관리 방법을 확인한 뒤, 폐기된 키를 참조하는 배포 작업을 목록으로 정리해야 합니다.
키 종류에 따라 교체 계획도 달라집니다. Apple은 개인 키는 사용자마다 유효한 키를 하나만 가질 수 있고, 팀 키는 여러 개를 만들 수 있다고 안내합니다. 따라서 팀 키는 새 키를 준비해 사용하는 작업부터 확인한 뒤 기존 키 사용처를 옮길 수 있지만, 개인 키는 같은 방식으로 기존 키와 새 키를 겹쳐 운영할 수 있다고 가정하면 안 됩니다. 키 생성 및 관리 규칙을 확인하고, 계정 역할에 새 키 생성 권한이 있는지도 먼저 살펴보세요.
유출이 의심된다면 먼저 해당 키를 폐기해야 합니다. 반대로 계획된 교체라면 키 유형과 현재 자동화의 참조 위치를 확인한 뒤 변경 순서를 세웁니다. 두 상황을 같은 절차로 처리하면 긴급 차단이 늦어지거나, 교체 작업 중 배포 환경이 인증 정보를 찾지 못할 수 있습니다.
새 키를 발급한 뒤 어디를 바꿔야 하나요?
새 키가 준비되면 Key ID, 필요한 경우 Issuer ID, p8 개인 키의 내용 또는 파일 경로를 한 묶음으로 점검합니다. fastlane은 API Key를 파일 경로나 키 내용으로 설정할 수 있으므로, 실제 배포 환경이 어떤 방식을 사용하는지 확인해야 합니다. fastlane의 App Store Connect API 설정 설명을 기준으로 저장 위치와 읽기 경로를 대조하세요.
첫 단계: 사용처를 목록으로 만듭니다
배포 lane, CI 작업, 예약 실행 스크립트, 원격 맥의 환경 변수와 비밀 저장소를 확인합니다. 과거 키의 Key ID나 p8 파일명을 검색해 오래된 참조가 남아 있는지 찾습니다. 개인 키와 팀 키 모두에서, 눈에 보이는 fastlane 설정만 바꾸고 끝내지 않는 것이 중요합니다. 예약 작업이 별도의 실행 계정이나 작업 폴더에서 동작한다면 그쪽 설정도 확인해야 합니다.
다음 단계: 새 정보만 안전하게 전달합니다
Key ID와 필요한 Issuer ID를 새 키 기준으로 설정하고, p8 파일을 사용하는 경우 fastlane이 접근할 정확한 경로를 지정합니다. 키 내용을 직접 사용하는 구성이라면 인코딩 방식과 환경 변수 이름을 기존 설정에 맞춥니다. 설정 항목은 fastlane의 API Key 작업 문서에서 확인할 수 있습니다.
개인 키는 저장소에 올리지 말고, 로그나 클라이언트 코드에도 넣지 않습니다. 원격 맥을 사용하는 경우에는 배포 작업을 실행하는 계정이 비밀 저장소에서 새 값을 읽을 수 있는지, 키 파일 접근 권한이 필요한 범위로 제한됐는지 확인합니다. 원격 환경의 자격 증명 취급 원칙은 ArmVNC의 데이터 및 개인정보 안내에서도 확인할 수 있습니다.
p8 파일이 새것이어도 Key ID가 이전 값이면 인증이 실패할 수 있습니다. 키 내용, 식별자, 실행 환경의 설정 출처를 함께 확인하고, 비밀 값 자체는 로그에 남기지 마세요.
마지막 단계: 저장 위치와 실행 경로를 함께 검증합니다
fastlane 설정에서 키 파일 경로를 지정했다면, 원격 맥의 실제 실행 계정과 작업 디렉터리에서 해당 경로를 읽을 수 있는지 확인합니다. 환경 변수 방식이라면 대화형 터미널에서만 값이 설정되어 있지 않은지도 점검합니다. 예약 실행이나 CI에서는 별도의 환경을 사용할 수 있으므로, 수동 실행에서 성공했다는 사실만으로 자동화까지 정상이라고 판단할 수 없습니다.
복구 완료를 어떤 기준으로 확인해야 하나요?
인증이 성공했다는 로그만으로 배포 체인 전체가 복구된 것은 아닙니다. API 접근 확인, 업로드 완료, App Store Connect에서의 후속 처리 상태를 따로 봐야 합니다. 우선 새 키의 역할에 맞는 낮은 위험도의 API 작업을 수행하고, 이후 프로젝트가 실제로 사용하는 업로드 또는 TestFlight 작업을 검증합니다.
아래 항목을 확인한 뒤 배포 작업을 다시 진행합니다.
- [ ] App Store Connect에서 새 키가 발급됐고, 필요한 계정 역할로 관리되고 있습니다.
- [ ] 새 Key ID와 해당 p8 파일 또는 키 내용이 한 쌍으로 설정돼 있습니다.
- [ ] 필요한 경우 Issuer ID가 fastlane 설정에 반영돼 있습니다.
- [ ] 원격 맥의 실행 계정과 자동화 작업이 새 비밀 값을 읽습니다.
- [ ] 저장소, 클라이언트 코드, 로그에 개인 키가 노출되지 않았습니다.
- [ ] 권한에 맞는 API 확인 작업이 성공했습니다.
- [ ] 실제 업로드 작업의 완료 여부와 App Store Connect의 처리 상태를 별도로 확인했습니다.
인증 확인이 성공했는데 업로드가 실패한다면 API 키 문제로 단정하지 마세요. 업로드 작업의 권한, 앱 선택, 전달 결과와 App Store Connect 쪽의 처리 상태를 따로 살펴야 합니다. 인증 성공은 자격 증명이 받아들여졌다는 뜻이지, 앱이 정상적으로 전달되고 후속 처리가 끝났다는 뜻은 아닙니다.
자주 묻는 질문
폐기한 키를 다시 활성화할 수 있나요?
아니요. Apple이 안내하는 방식으로 폐기된 API Key를 다시 켤 수는 없습니다. 이전 p8 파일을 다시 찾아도 키 상태가 바뀌지 않으므로 새 키를 발급하고 모든 참조 위치를 교체해야 합니다. 유출이 의심된다면 먼저 폐기하고, 이후 계정 권한과 자동화 작업에 맞는 새 키를 준비합니다.
fastlane에서 API Key 오류가 나면 무엇부터 확인하나요?
JWT 생성과 만료 여부를 먼저 확인하고, API Key의 폐기 상태는 별도로 점검합니다. 그다음 새 Key ID와 p8 파일이 짝을 이루는지, Issuer ID가 필요한 설정에서 누락되지 않았는지 확인하세요. 키 권한과 fastlane이 실제로 읽는 환경 변수 또는 파일 경로도 함께 점검해야 오류 원인을 구별할 수 있습니다.
키를 교체할 때 자동화의 어떤 부분을 살펴야 하나요?
fastlane lane뿐 아니라 CI 비밀 저장소, 환경 변수, 원격 맥의 키 파일과 예약 작업도 점검해야 합니다. 각각이 이전 Key ID나 p8 파일을 참조하는지 확인하고 새 값으로 바꿉니다. 개인 키와 팀 키는 동시에 유효하게 운용할 수 있는 조건이 다를 수 있으므로, 새 키로 전환할 수 있는 순서도 키 종류에 맞춰 계획합니다.
원격 맥에서 p8 파일을 어떻게 바꾸나요?
새 p8 파일을 저장소나 공개된 코드에 넣지 않고, 접근이 제한된 비밀 저장소 또는 보호된 경로로 전달합니다. fastlane 설정이 가리키는 파일 위치와 실행 계정의 읽기 권한을 확인하고, Key ID와 Issuer ID도 함께 교체합니다. 마지막으로 자동화 실행 환경에서 새 설정을 읽는지 확인한 뒤, API 확인과 실제 업로드를 각각 검증합니다.
폐기된 키를 사용하는 기존 방식은 인증이 갑자기 끊길 수 있고, CI와 원격 작업마다 오래된 값이 남아 있으면 원인 파악에도 시간이 듭니다. 자체 맥을 배포 전용으로 두면 하드웨어 비용과 상시 관리가 필요하고, 로컬 개발 환경에 빌드와 업로드를 몰아주면 다른 작업과 자원을 나눠 써야 합니다. 반면 원격 맥 iOS 자동 배포 환경은 macOS 실행 환경을 분리해 쓸 수 있어, 임시 테스트나 안정적인 배포 실행 환경이 필요한 팀에 선택지가 됩니다. 다만 장기간 상시 부하가 크거나 물리 장치 연결이 필요한 작업이라면 직접 보유한 맥이 더 적합할 수 있습니다. 원격 실행 환경을 검토한다면 한국에서 이용할 수 있는 맥 원격 사용 옵션과 원격 맥 이용 도움말을 비교해 현재 배포 흐름에 맞는지 확인할 수 있습니다.
자주 묻는 질문
폐기한 App Store Connect API Key를 다시 활성화할 수 있나요?
아니요. Apple은 폐기한 API Key를 다시 활성화하는 방법을 제공하지 않습니다. 기존 p8 파일을 다시 내려받거나 설정을 되돌려도 폐기 상태는 바뀌지 않습니다. 새 키를 발급한 다음 fastlane 설정과 이를 참조하는 자동화 작업을 모두 새 정보로 바꿔야 합니다. 키가 유출된 상황이라면 복구 작업보다 먼저 폐기 처리를 완료해야 합니다.
fastlane에서 API Key가 유효하지 않다고 나오면 무엇부터 확인하나요?
오류 문구만으로 키가 폐기됐다고 단정하지 마세요. JWT 생성과 만료, Key ID와 p8 파일의 짝, Issuer ID 입력 여부, 키의 역할 권한, fastlane이 실제로 읽는 설정 경로를 따로 확인해야 합니다. 새 토큰으로 인증이 되는지와 업로드 작업이 완료되는지도 별개로 살펴야 원인을 좁힐 수 있습니다.
새 API Key를 만들면 어떤 자동화 설정을 바꿔야 하나요?
저장소의 fastlane 설정뿐 아니라 CI 비밀 저장소, 환경 변수, 원격 맥의 키 파일 경로, 예약 작업과 배포 스크립트에서 이전 Key ID나 p8 파일을 참조하는지 확인해야 합니다. 새 키로 바꾼 뒤에는 각 작업이 실제로 새 비밀 값을 읽는지 검증합니다. 개인 키와 팀 키는 교체 시 기존 키와 함께 운영할 수 있는 조건이 다릅니다.
원격 맥에서 fastlane이 쓰는 p8 파일은 어떻게 안전하게 교체하나요?
새 p8 파일을 저장소나 앱 코드에 넣지 말고 접근을 제한한 비밀 저장소 또는 보호된 원격 맥 경로로 전달합니다. fastlane 설정의 파일 경로와 실행 계정의 읽기 권한을 확인하고, Key ID와 Issuer ID도 새 키 기준으로 맞춥니다. 교체 뒤에는 로그에 키 내용이 출력되지 않는지 확인한 다음 권한이 낮은 검증 작업부터 실행합니다.
연결 키 교체부터 업로드 검증까지, ArmVNC 원격 맥에서 이어가세요
전용 맥에서 새 키를 설정하고 빌드와 업로드가 정상적으로 진행되는지 차례로 확인할 수 있습니다.