KappS Wissensdatenbank · Blog

Die App Store Connect API 2026: Eine Schritt-für-Schritt-Anleitung zu Keys, JWT-Tokens und Rate

Blog Leitfaden

Die App Store Connect API ist die REST-Schicht hinter der Weboberfläche von App Store Connect: Apple selbst fasst zusammen, dass sie „die Automatisierung der Aktionen ermöglicht, die Sie in App Store Connect durchführen", und warnt ausdrücklich, dass alles, was Sie darüber ändern, Produktionsdaten sind. Genau dieser eine Satz ist der Grund für diesen Leitfaden – ein funktionierender Schlüssel und ein gültiges Token genügen, um Nutzer einzuladen, Bundle-IDs zu ändern, Builds hochzuladen, App Store-Metadaten zu bearbeiten und Verkaufsberichte herunterzuladen, ganz ohne Browser. Dieser Leitfaden für 2026 behandelt die Zugriffsanfrage, die nur der Account Holder stellen kann, Team- versus individuelle Schlüssel, das ES256-JWT, das jeden Aufruf autorisiert, das Ratenlimit pro gleitender Stunde und HTTP 429, das Lesen von Fehlern, Paging, Asset-Uploads und die Sperrung von Schlüsseln.

Die Kurzfassung: Der Account Holder beantragt einmalig den API-Zugriff; ein Admin erzeugt einen rollenbasierten Team-Schlüssel (oder jeder Nutzer erzeugt einen eigenen individuellen Schlüssel); Ihr Code signiert ein kurzlebiges ES256-JWT, dessen kid die Schlüssel-ID und dessen aud appstoreconnect-v1 ist; jede Antwort trägt einen X-Rate-Limit-Header, und das Überschreiten des Stundenlimits liefert 429 RATE_LIMIT_EXCEEDED.

Schritt 1 — Wissen, was die API tatsächlich erreicht

Bevor Sie etwas anfordern, kartieren Sie die Oberfläche, die Sie automatisieren wollen, denn die Rolle des Schlüssels bestimmt, was erreichbar ist. Apple dokumentiert Ressourcen für In-App-Käufe und automatisch verlängerbare Abos, TestFlight-Beta-Builds, Tester und Gruppen, Xcode Cloud-Daten und Workflows, Users and Access, Provisioning (Bundle-IDs, Capabilities, Zertifikate, Geräte, Profile), App-Metadaten und Einreichungen, App-Clip-Erlebnisse, Reporting (Umsatz- und Finanzberichte), Power and Performance Metrics sowie Kundenbewertungen mit ihren Antworten. Zwei strukturelle Fakten sind wichtig: Die Ressourcen liefern konsistentes JSON mit Beziehungslinks zur Navigation zwischen ihnen, und wenn Ihr Konto zum Apple Developer Enterprise Program gehört, verweist Apple Sie auf die Enterprise Program API statt auf diese. Bauen Sie nicht gegen die falsche API und entdecken Sie es erst bei einem Release.

Schritt 2 — Die Zugriffsanfrage, die nur der Account Holder stellen kann

Der API-Zugang ist nicht standardmäßig aktiviert und kein Schalter pro Schlüssel. Der Kontoinhaber meldet sich an, öffnet Nutzer und Zugriff > Integrationen (die Seite öffnet sich mit ausgewählter App Store Connect-API), klickt auf Zugriff anfordern, stimmt den Bedingungen zu und reicht ein. Apple prüft den Antrag dann und genehmigt ihn „im Einzelfall" – was bedeutet, dass die richtige Reihenfolge ist, dies einzureichen, bevor Sie jemandem einen Automatisierungstermin versprechen, und nicht am Tag des Releases. Nach der Genehmigung enthält dieselbe Seite die Aussteller-ID und die Schlüsselliste.

Schritt 3 — Wählen Sie Team-Schlüssel oder individuelle Schlüssel, und zwar richtig

Apple definiert zwei Schlüsseltypen, und sie sind nicht austauschbar:

  • Team-Schlüssel – werden vom Kontoinhaber oder einem Admin erzeugt, gelten für alle Apps im Konto, und ihr Zugriff wird durch die von Ihnen gewählte Rolle festgelegt. Sie können einen Team-Schlüssel nicht auf bestimmte Apps beschränken: „Team-API-Schlüssel gelten für alle Apps, daher kann der App-Zugriff für einen API-Schlüssel nicht eingeschränkt werden."
  • Individual keys – von einem Nutzer im eigenen Profil erzeugt, mit den Apps und der Rolle dieses Nutzers. Rollen, die einen Schlüssel erstellen dürfen, sind Account Holder, Admin, App Manager, Customer Support, Developer und Marketing, und jeder Nutzer kann nur einen aktiven Schlüssel gleichzeitig halten. Die Dokumentation von Apple nennt zwei harte Grenzen, die Sie bei der Planung berücksichtigen sollten: Einzelne Schlüssel können die Provisioning-Endpunkte oder notaryTool nicht nutzen.

Daraus folgen zwei operative Regeln. Name und Zugriffsebene eines Schlüssels lassen sich nach der Erstellung nicht bearbeiten – um eines von beiden zu ändern, widerrufen Sie den Schlüssel und erzeugen einen neuen. Und die private Hälfte ist genau einmal herunterladbar: Wenn Ihre Pipeline sie verliert, hilft nur ein neuer Schlüssel, kein erneuter Download. Führen Sie einen serverseitigen Secret Store und behandeln Sie die Datei .p8 genau wie ein Datenbankpasswort.

Schritt 4 — Das ES256-Token erstellen, das Apple tatsächlich akzeptiert

Jede Anfrage benötigt ein JWT, das mit dem privaten Schlüssel signiert ist, den Sie heruntergeladen haben. Die Token-Dokumentation von Apple legt die Header-Felder fest: alg muss ES256 sein, kid ist Ihre private Schlüssel-ID (zum Beispiel 2X9R4HXF34) und typ ist JWT. Bei einem Team-Schlüssel enthält der Payload iss (die Issuer-ID, zum Beispiel 57246542-96fe-1a63-e053-0824d011072a), iat und exp in UNIX-Epoch-Zeit sowie aud mit dem Wert appstoreconnect-v1. Die Ablaufregel ist die, die im Produktivbetrieb wehtut: Tokens, die mehr als 20 Minuten in der Zukunft ablaufen, sind ungültig, außer für die Ressourcen, die Apple als Ausnahmen auflistet. Erzeugen Sie kurze Tokens, verwenden Sie sie innerhalb des Zeitfensters erneut und cachen Sie keines über das Fenster hinaus. Haben Sie mehrere Team-Schlüssel, muss die kid zu demselben privaten Schlüssel gehören, der das Token signiert – ein nicht zusammenpassendes Paar scheitert an der Authentifizierung, nicht an der Autorisierung.

Einzelschlüssel verwenden eine etwas andere Payload: kein iss, sondern einen sub-Claim mit dem Wert user. Wenn Sie einen Token-Builder für beide Schlüsseltypen schreiben, machen Sie diesen Unterschied im Code explizit, statt ihn zur Laufzeit abzuleiten.

Schritt 5 — Begrenzen Sie den Token, statt zu hoffen, dass er nicht geleakt wird

Apple unterstützt einen optionalen scope-Claim: eine Liste der Anfragen, die dieses Token stellen darf, wobei jeder Eintrag aus HTTP-Methode plus URL-Pfad plus optionalem Query-String besteht – zum Beispiel GET /v1/apps/123 oder GET /v1/apps?filter[platform]=IOS. Ein Token, das mit einem Scope vorgelegt wird, der die Anfrage nicht abdeckt, wird abgelehnt. Die Begründung von Apple ist es wert, jedem entgegenzuhalten, der Scope als Overhead abtut: Wenn Sie versehentlich ein Token an eine unbefugte Partei weitergeben, reduziert ein begrenzter Scope, was diese Partei damit tun kann. Automatisierung, die nur Verkaufsberichte liest, sollte einen schreibgeschützten Scope tragen, nicht die volle Befugnis der Rolle des Schlüssels.

Schritt 6 — Beachten Sie das rollierende Stundenlimit und behandeln Sie 429 als Zustand, nicht als Fehler

Die Rate-Limits dieser API gelten pro Schlüssel und sind nicht als eine einzige feste Zahl dokumentiert. Jede Antwort enthält einen X-Rate-Limit-Header mit user-hour-lim (erlaubte Anfragen pro Stunde für diesen Schlüssel) und user-hour-rem (verbleibende Anfragen); Apple zeigt im eigenen Beispiel ein Limit von 3500 Anfragen pro Stunde bei 500 verbleibenden und weist darauf hin, dass die tatsächlichen Limits variieren können. Das Zeitfenster ist eine rollende Stunde: Der verbleibende Wert entspricht jederzeit Ihrem Limit minus allem, was Sie in den vergangenen 60 Minuten gesendet haben. Überschreiten Sie es, antwortet die API mit HTTP 429 und dem Fehlercode RATE_LIMIT_EXCEEDED. Daraus folgen zwei Design-Konsequenzen: Lesen Sie user-hour-rem und drosseln Sie vorbeugend, wenn er niedrig ist, und behandeln Sie einen 429 als „protokollieren und den Job für später einreihen“ statt als fatalen Fehler – ein nächtlicher Export, der bei einem 429 laut scheitert, scheitert jede Nacht, in der er sich der Obergrenze nähert.

Schritt 7 – Lesen Sie Fehler zuerst am Statuscode ab, dann am Fehlerobjekt

Laut der Fehlerhilfe von Apple bedeutet ein Statuscode im 200er-Bereich Erfolg, und der Body enthält die Daten; ein Code im 400er- oder 500er-Bereich bedeutet, dass die Anfrage fehlgeschlagen ist, und der Body enthält die Details. Das Fehlerobjekt enthält außerdem einen code für die programmatische Verarbeitung und in vielen Fällen ein source-Objekt, das genau auf das Problem in Ihrer Anfrage verweist – ein JSON-Pointer in die Payload oder der Query-Parameter, der den Fehler ausgelöst hat. Lesen Sie die Quelle, bevor Sie die Anfrage neu schreiben; der Unterschied zwischen „mein JSON ist an dieser Stelle fehlerhaft" und „meine Rolle darf das nicht" ist der Unterschied zwischen einer Fünf-Minuten-Korrektur und einem Support-Ticket.

Schritt 8 – Blättern Sie durch große Ergebnismengen, statt ein größeres Limit zu raten

Antworten für Sammlungen enthalten Paging-Informationen und zugehörige Links – ein Paginierungsobjekt plus die Antwort-Links, die Sie weiterführen. Schreiben Sie die Schleife, die diesen Links folgt, bis der Cursor erschöpft ist; gehen Sie nicht davon aus, dass ein einzelner Aufruf jeden Build, jeden Tester oder jede App Store-Version zurückgibt, und hardcodieren Sie keine Seitengröße, die Sie für „groß genug" halten. Ein Bericht, der still abschneidet, ist schlimmer als ein langsamer.

Schritt 9 — Laden Sie die Assets in der Reihenfolge hoch, die Apple verlangt

Binäre Assets – Screenshots, App-Vorschauen, Anhänge für die App-Prüfung, Routing-App-Coverage-Dateien – folgen einem vierstufigen Ablauf: eine Asset-Reservierung vornehmen (Asset-Typ, Dateiname, Größe in Bytes), die Bytes über die in dieser Antwort zurückgegebenen Operationen hochladen, den Upload abschließen und dann prüfen, ob App Store Connect das Asset verarbeitet hat. Eine erfolgreiche Reservierung liefert eine Reservierungs-ID, eine Reihe von Upload-Operationen, die Dateiattribute und einen Auslieferungsstatus von AWAITING_UPLOAD. Große Dateien kommen als mehrere Operationen zurück, die Ihnen Offset und Länge jedes Teils nennen – die API teilt sie bewusst auf, damit eine instabile Verbindung Sie nicht die ganze Datei kostet. Beachten Sie außerdem, dass die Ressourcen für App-Screenshots, App-Vorschauen und In-App-Event-Screenshots veraltet sind: Verwalten Sie Screenshots, Vorschauen und In-App-Event-Medien stattdessen über die App Asset Library und Placements. Und lassen Sie eine Reservierung nicht halbfertig liegen; laut Apple haben Sie nach der Reservierung nur begrenzt Zeit, den Upload abzuschließen.

Schritt 10 — Rotieren und widerrufen, als wäre der Schlüssel ein Zugangsdatum

Der Kontoinhaber oder ein Admin kann Team-Schlüssel widerrufen sowie die individuellen Schlüssel jedes Teammitglieds; Nutzer können ihre eigenen widerrufen. Der Widerruf erfolgt sofort und ist dauerhaft – ein widerrufener Schlüssel kann nicht wiederhergestellt werden –, weshalb der Widerruf die richtige Notfallmaßnahme ist und kein letztes Mittel. Widerrufene Schlüssel bleiben auf der Seite „API Keys“ unter der Überschrift „Revoked“ 30 Tage lang sichtbar. Das reicht aus, um nach einem Vorfall die Frage „Welcher Schlüssel war das?“ zu beantworten, aber nicht als Audit-Trail – protokollieren Sie Schlüssel-IDs daher zusammen mit Ihren Automatisierungsläufen. Wenn eine Person grundsätzlich keinen API-Zugriff erhalten soll, kann ein Admin schließlich die Berechtigung Generate Individual API Keys für diesen Nutzer unter People entziehen – die Kontrolle existiert, nutzen Sie sie, statt sich auf Richtlinien zu verlassen.

Die Checkliste

  • Der Kontoinhaber hat die Zugriffsanfrage gestellt, und sie ist genehmigt.
  • Schlüsseltyp bewusst gewählt: Team-Schlüssel für kontoweite Automatisierung, individueller Schlüssel für den Bereich eines einzelnen Nutzers.
  • Privater Schlüssel einmalig in einem Secret Manager gespeichert, mit dokumentiertem Verantwortlichen.
  • Token-Builder: ES256, kid passend zum Signaturschlüssel, aud=appstoreconnect-v1, exp innerhalb von 20 Minuten, scope so eng wie möglich gefasst.
  • Der Client liest X-Rate-Limit, drosselt vor dem Limit und reiht bei 429 in die Warteschlange ein.
  • Sammlungsaufrufe folgen den Paging-Links; nichts setzt eine vollständige erste Seite voraus.
  • Reservierung für Asset-Uploads, Teile, Commit, Verifizierungsstatus geprüft.
  • Widerrufene Schlüssel mit Grund und Datum protokolliert; 30-Tage-Sichtbarkeit nicht als Audit-Log behandelt.

Apple pflegt ein Changelog der Versionshinweise für die API. Apple ergänzt im Laufe der Zeit Felder und Ressourcen, lesen Sie es daher erneut, bevor Sie Ihre Integration als abgeschlossen betrachten.

Quellen

Sie verwalten Entwicklerkonten im großen Stil? Wir übernehmen die operative Seite.

Klicken Sie, um eine Datei auszuwählen · Rechtsklick → Einfügen oder Ctrl/⌘+V drücken, um einen Screenshot einzufügen

Sie können eine Datei auch auf dieses Feld ziehen.

Wir antworten an die von Ihnen angegebene E-Mail-Adresse. Ihre Daten bleiben bei KappS.

✔ Eingereicht

Wir haben Ihre Nachricht erhalten und antworten innerhalb von 24 Stunden.


← Zurück zum Bearbeiten