2026年のApp Store Connect API:キー、JWTトークン、レート制限を
App Store Connect APIはApp Store Connectのウェブインターフェースの背後にあるRESTレイヤーです。Apple自身の要約によれば、「App Store Connectで行う操作の自動化を可能にする」ものであり、このAPIを通じて変更した内容は本番データであると明示的に警告しています。この一文こそが本ガイドの存在理由です。有効なキーと正しいトークンさえあれば、ブラウザを使わずにユーザーの招待、バンドルIDの変更、ビルドのアップロード、App Storeメタデータの編集、売上レポートのダウンロードまでできてしまいます。本2026年版ガイドでは、アカウント所有者しか申請できないアクセスリクエスト、チームキーと個人キーの違い、すべての呼び出しを認可するES256 JWT、ローリング1時間のレート制限とHTTP 429、エラーの読み方、ページング、アセットのアップロード、キーの失効までを扱います。
一行でまとめると:アカウント保有者がAPIアクセスを一度リクエストし、管理者がロールスコープのチームキーを生成する(または各ユーザーが個別のキーを生成する)。コードは短命のES256 JWTに署名し、そのkidはキーID、audはappstoreconnect-v1となる。すべてのレスポンスにはX-Rate-Limitヘッダーが付き、時間あたりの上限を超えると429 RATE_LIMIT_EXCEEDEDが返る。
ステップ1 — APIが実際にどこまで届くかを知る
何かをリクエストする前に、自動化しようとしている範囲を把握しておくこと。キーの役割によって、どこまでアクセスできるかが決まるからだ。Appleは、アプリ内課金と自動更新サブスクリプション、TestFlightのベータビルド・テスター・グループ、Xcode Cloudのデータとワークフロー、Users and Access、Provisioning(バンドルID、ケイパビリティ、証明書、デバイス、プロファイル)、App Metadataと申請、App Clip体験、Reporting(売上レポートと財務レポート)、Power and Performance Metrics、そしてカスタマーレビューとその返信に関するリソースを文書化している。押さえるべき構造上の事実は2つある。リソースは関係リンク付きの一貫したJSONを返し、それを使ってリソース間を移動できること。そして、アカウントがApple Developer Enterprise Programに属している場合、AppleはこのAPIではなくEnterprise Program APIを案内するということだ。誤ったAPIに対して開発を進め、リリース時にそのことに気づく、という事態は避けたい。
ステップ2 — アカウント所有者しか申請できないアクセスリクエスト
APIアクセスはデフォルトでは有効になっておらず、キーごとの切り替えでもありません。アカウント所有者がサインインし、ユーザーとアクセス > 連携を開き(ページはApp Store Connect APIが選択された状態で開きます)、アクセスをリクエストをクリックし、規約に同意して送信します。その後Appleがリクエストを審査し、「ケースバイケースで」承認します。つまり正しい順序は、誰かに自動化の日程を約束する前にこれを申請することであり、リリース当日に申請することではありません。承認されると、同じページに発行者IDとキー一覧が表示されます。
ステップ3 — チームキーか個人キーかを正しく選ぶ
Appleは2種類のキータイプを定義しており、これらは互換性がありません:
- チームキー — アカウント所有者または管理者が生成し、アカウント内のすべてのアプリに適用され、アクセス権は選択したロールによって設定されます。チームキーを特定のアプリに限定することはできません。「チームAPIキーはすべてのアプリに適用されるため、APIキーに対してアプリのアクセスを制限することはできません」。
- 個人キー — ユーザーがプロフィールで生成するもので、そのユーザーのアプリとロールを引き継ぎます。作成できるロールはアカウント所有者、管理者、アプリマネージャ、カスタマーサポート、デベロッパー、マーケティングで、各ユーザーが同時に保持できる有効なキーは1つだけです。Appleのドキュメントには、設計時に考慮すべき厳格な制限が2つあります。個人キーはプロビジョニングのエンドポイントや
notaryToolを使用できません。
そこから2つの運用ルールが導かれます。キーの名前とアクセスレベルは生成後に編集できません。どちらかを変更するには、キーを取り消して新しいキーを生成してください。また、秘密鍵の半分は一度だけダウンロードできます。パイプラインで失われた場合の対処は再ダウンロードではなく新しいキーの生成です。サーバー側のシークレットストアを用意し、.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クレームを持ちます。両方のキータイプに対応するトークンビルダーを1つ書く場合は、この違いを実行時に推測するのではなく、コード上で明示してください
ステップ5 — 漏えいしないことを願うのではなく、トークンのスコープを絞る
Appleは任意のscopeクレームをサポートします。これはこのトークンが実行を許可されるリクエストのリストで、各エントリはHTTPメソッド+URLパス+任意のクエリ文字列です。例えばGET /v1/apps/123やGET /v1/apps?filter[platform]=IOSです。リクエストをカバーしないスコープを伴って提示されたトークンは拒否されます。Appleが示す理由は、スコープはオーバーヘッドだと主張する相手にそのまま引用する価値があります。誤ってトークンを権限のない第三者と共有してしまった場合、スコープを限定しておけばその第三者ができることを減らせます。販売レポートを読むだけの自動化には、鍵のロールが持つ全権限ではなく、読み取り専用のスコープを付与すべきです。
ステップ6 — ローリングアワーを守り、429をエラーではなく状態として扱う
このAPIのレート制限はキーごとに設定されており、単一の固定値として文書化されているわけではありません。すべてのレスポンスにはX-Rate-Limitヘッダーが付与され、その中にuser-hour-lim(そのキーで1時間に許可されるリクエスト数)とuser-hour-rem(残りのリクエスト数)が含まれます。Appleの公式例では1時間あたり3500リクエスト、残り500と示されており、実際の制限値は変動し得ると明記されています。ウィンドウはローリング1時間方式です。つまり、ある時点の残数は、制限値から直近60分間に送信したすべてのリクエストを差し引いた数になります。超過するとAPIはHTTP 429とRATE_LIMIT_EXCEEDEDエラーコードを返します。設計上の帰結は2つあります。user-hour-remを読み取り、少なくなったら先回りしてスロットリングすること。そして429を致命的エラーではなく「ログに記録してジョブを後回しにキューへ積む」ものとして扱うことです。上限付近で推移するたびに429で大騒ぎする夜間エクスポートは、毎晩失敗することになります。
ステップ7 — 失敗はまずステータスコードから読み、次にエラーオブジェクトを確認する
Appleのエラーガイダンスによると、200番台のステータスコードは成功を意味し、ボディにデータが含まれます。400番台または500番台のコードはリクエストの失敗を意味し、ボディに詳細が含まれます。エラーオブジェクトにはプログラムで処理するためのcodeも含まれ、多くの場合、リクエストのどこが問題だったかを正確に示すsourceオブジェクト(ペイロードへのJSONポインタ、またはエラーを引き起こしたクエリパラメータ)が付属します。リクエストを書き直す前にsourceを読みましょう。「このパスでJSONが不正」と「自分のロールではこれができない」の違いは、5分で直る修正とサポートチケットの違いです。
ステップ8 — 上限を大きく見積もるのではなく、大きな結果セットをページングする
コレクションのレスポンスにはページング情報と関連リンクが含まれます。ページネーションオブジェクトと、次へ進むためのレスポンスリンクです。カーソルが尽きるまでこれらのリンクをたどるループを書いてください。1回の呼び出しで全ビルド、テスター、App Storeバージョンが返ってくると仮定してはいけませんし、「十分大きい」と思うページサイズをハードコードしてもいけません。黙って途中で切れるレポートは、遅いレポートより悪いものです。
ステップ9 — Appleが要求する順序で素材をアップロードする
バイナリ素材(スクリーンショット、アプリプレビュー、App Review用の添付ファイル、ルーティングアプリのカバレッジファイル)は、4ステップのフローに従います。まず素材の予約を作成し(素材タイプ、ファイル名、バイト単位のサイズ)、そのレスポンスで返された操作を使ってバイトをアップロードし、アップロードをコミットしてから、App Store Connectが素材を処理したことを確認します。予約が成功すると、予約ID、一連のアップロード操作、ファイル属性、そしてAWAITING_UPLOADという配信ステータスが返されます。大きなファイルは複数の操作として返され、各部分のオフセットと長さが示されます。APIが意図的に分割することで、不安定な接続でもファイル全体を失わずに済みます。また、アプリのスクリーンショット、アプリプレビュー、アプリ内イベントのスクリーンショットの各リソースは非推奨になっています。スクリーンショット、プレビュー、アプリ内イベントのメディアは、App Asset Libraryとプレースメントで管理してください。予約を中途半端なままにしないでください。Appleでは、予約後にアップロードを完了するまでの時間が限られていると定められています。
ステップ10 — キーを認証情報としてローテーションし失効させる
アカウント所有者または管理者は取り消すことができますチームキーとチームメンバー個人のキーを。ユーザーは自分のキーを取り消せます。取り消しは即時かつ永久的です — 取り消されたキーは復元できません — そのため取り消しは最後の手段ではなく、正しい緊急対応となります。取り消されたキーはAPIキーページの「取り消し済み」見出しの下に30日間表示され続けます。これはインシデント後に「あのキーはどれだったか」を確認するには十分ですが、監査証跡として使うには短すぎるため、自動化の実行と併せてキーIDをログに記録してください。最後に、ある人物にAPIアクセスを一切与えるべきでない場合は、管理者が個人用APIキーの生成権限をそのユーザーからユーザー管理で外せます — その制御は存在するので、ポリシーに頼らず活用してください。
チェックリスト
- アカウント所有者がアクセスリクエストを申請し、承認済みです。
- キーの種類は意図的に選択:アカウント全体の自動化にはチームキー、特定ユーザーの範囲には個人キー。
- 秘密鍵はシークレットマネージャーに1回だけ保存し、所有者を文書化する。
- トークンビルダー:
ES256、署名キーと一致するkid、aud=appstoreconnect-v1、expは20分以内、scopeは作業に必要な最小限に。 - クライアントは
X-Rate-Limitを読み取り、上限に達する前にバックオフし、429発生時はキューに格納します。 - 収集呼び出しはページングリンクに従います。最初のページが完全であることは前提にしません。
- アセットアップロードの予約、パーツ、コミット、検証状態を確認済み。
- 失効したキーは理由と日付とともに記録。30日間の可視性は監査ログとして扱わない。
AppleはAPIのリリースノートの変更履歴を管理しています。Appleは時間とともにフィールドやリソースを追加するため、統合を完了とみなす前に再読してください。
情報源
- Apple デベロッパー — App Store Connect API概要:developer.apple.com/documentation/appstoreconnectapi
- Apple Developer — App Store Connect API(ヘルプ、アクセス申請、キー):developer.apple.com/help/app-store-connect/get-started/app-store-connect-api
- Apple Developer — APIキーの作成:creating-api-keys-for-app-store-connect-api
- Apple デベロッパー — APIリクエスト用トークンの生成:generating-tokens-for-api-requests
- Apple Developer — レート制限の特定:identifying-rate-limits
- Apple Developer — エラーの解釈と処理: interpreting-and-handling-errors
- Appleデベロッパー — 大規模データセット(ページング): large-data-sets
- Appleデベロッパー — アセットのアップロード:uploading-assets-to-app-store-connect
- Apple デベロッパー — APIキーの失効:revoking-api-keys
- Apple デベロッパー — App Store Connect APIリリースノート:app-store-connect-api-release-notes
デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。
メッセージを受け付けました。24時間以内に返信します。
← 編集に戻る