KappSナレッジベース · ブログ

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は時間とともにフィールドやリソースを追加するため、統合を完了とみなす前に再読してください。

情報源

デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。

クリックしてファイルを選択 · 右クリック→貼り付け、またはCtrl/⌘+Vでスクリーンショットを貼り付け

このボックスにファイルをドラッグすることもできます。

ご提供いただいたメールに返信します。お客様の情報はKappS内に留まります。

✔ 送信済み

メッセージを受け付けました。24時間以内に返信します。


← 編集に戻る