Asc API Automation

App Store Connect API Automation

This catalog's default way to drive App Store Connect from scripts and CI: an Apple-native toolchain — a ~30-line Swift/CryptoKit script mints the JWT, plain curl calls the REST API. No fastlane/spaceship, no Ruby gems, no Homebrew, consistent with the catalog's mise + no-third-party baselines.

When to invoke

• Writing release tooling: distribute a build to TestFlight groups, set what's-new, create the next App Store version, submit for review
• Pulling sales or App Store analytics reports on a schedule
• Debugging ASC API auth failures (401 NOT_AUTHORIZED) or rate limiting (429)
• Asked "should I use fastlane for this?"

Scope

Owns: token minting, curl conventions, and the endpoint cookbook below. Does NOT own:

• Building / uploading the binary — there is no REST endpoint for .ipa upload; builds arrive in ASC via Xcode Cloud (→ xcode-cloud-single-track-ci), a local xcodebuild -exportArchive / xcrun altool run (→ local-archive-export-upload), Xcode Organizer, or Transporter. This skill picks up after the build exists in ASC.
• .p8 key storage & leak prevention → build-time-secret-injection (Layer 2 secrets/.env) + apple-public-repo-security (rotate-first SOP).
• What metadata will pass review → app-store-review-rejections; this skill is how to submit, not what.

Keys: create, scope, store

Store per build-time-secret-injection Layer 2:

# secrets/.env (gitignored; .env.example committed)
ASC_KEY_ID=2X9R4HXF34
ASC_ISSUER_ID=57246542-96fe-1a63-e053-0824d011072a
ASC_KEY_PATH=secrets/AuthKey_2X9R4HXF34.p8

Mint the token (CryptoKit, zero dependencies)

Claims (verified against Apple's Generating tokens for API requests, 2026-07): header alg: ES256 (the only accepted algorithm), kid, typ: JWT; payload iss (Issuer ID, the UUID from Users and Access → Integrations — not your Team ID), iat, exp (invalid if more than 20 minutes ahead), aud: "appstoreconnect-v1", optional scope (array of allowed requests like "GET /v1/apps" — pin single-purpose tokens to single endpoints).

scripts/mint-asc-token.swift:

#!/usr/bin/env swift
import CryptoKit
import Foundation

let env = ProcessInfo.processInfo.environment
guard let keyID = env["ASC_KEY_ID"], let issuerID = env["ASC_ISSUER_ID"],
      let keyPath = env["ASC_KEY_PATH"] else {
    FileHandle.standardError.write(Data("Set ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_PATH (source secrets/.env)\n".utf8))
    exit(1)
}

func b64url(_ data: Data) -> String {
    data.base64EncodedString()
        .replacingOccurrences(of: "+", with: "-")
        .replacingOccurrences(of: "/", with: "_")
        .replacingOccurrences(of: "=", with: "")
}

let now = Int(Date().timeIntervalSince1970)
let header = #"{"alg":"ES256","kid":"\#(keyID)","typ":"JWT"}"#
// Apple rejects exp > 20 min ahead; 10 min leaves slack for clock skew.
let payload = #"{"iss":"\#(issuerID)","iat":\#(now),"exp":\#(now + 600),"aud":"appstoreconnect-v1"}"#
let signingInput = b64url(Data(header.utf8)) + "." + b64url(Data(payload.utf8))

let pem = try String(contentsOfFile: keyPath, encoding: .utf8)
let key = try P256.Signing.PrivateKey(pemRepresentation: pem)
let signature = try key.signature(for: Data(signingInput.utf8))  // ECDSA + SHA-256 = ES256
print(signingInput + "." + b64url(signature.rawRepresentation))  // rawRepresentation = r‖s, the JWT wire format

source secrets/.env
ASC_TOKEN=$(swift scripts/mint-asc-token.swift)
curl -sf -H "Authorization: Bearer $ASC_TOKEN" "https://api.appstoreconnect.apple.com/v1/apps?limit=200"

Mint fresh per run; a job that outlives the token re-mints instead of extending exp.

curl conventions

• JSON:API shape — write calls send Content-Type: application/json with the body wrapped as {"data": {"type": ..., "id": ..., "attributes": {...}, "relationships": {...}}}.
• Pagination — pass limit=200 (the max) and follow links.next until absent; the small default page size silently truncates lists otherwise.
• Rate limit — every response carries X-Rate-Limit: user-hour-lim:3500; user-hour-rem:… (rolling hour, per key; Apple says actual limits vary). Exceeding returns 429 RATE_LIMIT_EXCEEDED — back off and re-queue; a 429 lockout hits everything sharing that key, including CI.
• Errors are structured — read .errors[].detail. Triage: 401 = token/claims problem, 403 = key role or scope problem, 409 = resource state problem (e.g. version not in a submittable state).

Endpoint cookbook

The review-submission flow is the 2022+ reviewSubmissions model, which replaced the deprecated one-shot appStoreVersionSubmissions.

Pre-submission prerequisites the three-call flow doesn't mention

The POST reviewSubmissions → POST reviewSubmissionItems → PATCH submitted: true sequence above assumes the app is already submittable; in practice three preconditions block it and have no REST fix:

• App pricing must be set first. Apple's ASC Help confirms pricing has to be configured before submission (Set a price / Overview of submitting for review, help.apple.com/app-store-connect). A pricing write endpoint does exist — POST /v1/appPriceSchedules ("Add a Scheduled Price Change to an App") — but it doesn't help until the Paid Apps Agreement is accepted, which is web-UI-only (see "Steps with no ASC API at all" below). Observed in practice (exact error-code string not found in Apple's published API reference): a POST reviewSubmissions on an app with no price configured fails with a pricing-state error. Set the price once — via the API or the web UI — before automating the rest.
• An empty copyright attribute blocks submission. Apple's error-code family for a missing required attribute is documented on the developer forums as ENTITY_ERROR.ATTRIBUTE.REQUIRED for other required fields (e.g. companyName); the same shape is observed in practice for a blank copyright on the app/version resource — not confirmed against Apple's official attribute reference, so treat the exact code as observed-in-practice, not documented fact. Fix: always send a non-empty copyright string.
• A leftover non-COMPLETE reviewSubmissions blocks a new POST, and there is no DELETE. Apple's API reference publishes DELETE /v1/appStoreVersionSubmissions/{id} only for the deprecated pre-2022 model; the current reviewSubmissions resource has no DELETE operation. To clear a stuck submission, PATCH /v1/reviewSubmissions/<id> with {"data":{"type":"reviewSubmissions","id":"<id>","attributes":{"canceled":true}}} — state is a read-only response attribute (ReviewSubmissionUpdateRequest.Data.Attributes accepts only canceled / submitted / platform); after the PATCH the state transitions to CANCELING, one of the documented ReviewSubmission.Attributes.state values (alongside READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, UNRESOLVED_ISSUES, COMPLETING, COMPLETE). During WAITING_FOR_REVIEW, canceling returns the version to an editable state (observed as DEVELOPER_REJECTED, a documented AppVersionState value) without leaving an Apple rejection record — this is the withdrawal recipe when a submission needs correcting before Apple starts review.

Steps with no ASC API at all — must be clicked by a human

The three prerequisites above are gaps in an otherwise-scriptable flow. These are different: Apple publishes no REST resource for them at all, so no amount of scripting closes the gap — budget a manual, one-time (or rarely-repeated) click in the ASC web UI.

• Verified ✓ — Agreements, Tax, and Banking (including accepting the Paid Apps Agreement). Apple's App Store Connect API topic index (developer.apple.com/tutorials/data/documentation/AppStoreConnectAPI.md, checked 2026-09) lists every automatable area — App Store, TestFlight, Game Center, Provisioning, Xcode Cloud, Webhooks, Reporting, Users and Access, Alternative App Distribution — and "Agreements, Tax, and Banking" is absent from all of them; no agreements/taxForms/bankAccounts-shaped resource exists anywhere in the reference. ASC Help's Schedule price changes for apps page confirms the practical consequence for this skill's pricing prerequisite above: "If you've accepted the Paid Apps Agreement and submitted your app for review, you can schedule price changes for your app" — the Agreement is accepted only in ASC's Manage Agreements section, by the Account Holder, in the browser. This is the actual gate behind the "app pricing must be set first" prerequisite above, not a scriptable pricing endpoint being missing (as of 2026, POST /v1/appPriceSchedules does exist for pricing itself — but it 404s/403s until the Agreement is accepted, and the Agreement has no API path).
• Verified ✓ — App promo codes (whole-app free-download codes, Apps → <App> → Promo Codes). ASC Help's Request and manage promo codes page (developer.apple.com/help/app-store-connect/offer-promo-codes/request-and-manage-promo-codes) documents only the web click-path ("In Apps, select the app you want to view. In the sidebar, click Promo Codes. The Promo Code page opens with Generate selected.") with no REST alternative mentioned; no promoCodes-shaped resource appears in the API topic index either. Don't confuse this with Subscription Offer Codes, which do have a documented API (POST /v1/subscriptionOfferCodeCustomCodes and siblings under Subscription Offer Codes) — the API gap is specific to whole-app promo codes, not offer codes in general.

Release automation: SemVer, changelog, and explicit releaseType

• versionString = SemVer, sourced from the build, not reinvented in CI. Set it to the same value as the archived build's MARKETING_VERSION (CFBundleShortVersionString) — bump that once at the Xcode-project level (→ xcode-cloud-single-track-ci build-number & version automation), then read it back for the appStoreVersions call instead of maintaining a second version counter in release tooling.
• Changelog → whatsNew, generated once, written twice. Build the "What's New" text from git log <last-tag>..HEAD --oneline (or your conventional-commit tooling) in the release job, then PATCH it into both betaBuildLocalizations (TestFlight) and appStoreVersionLocalizations (App Store) per locale — one generated string, two writes, so testers and reviewers see the same notes.
• releaseType — set it explicitly, every time. The attribute is optional and Apple's schema documents no default value. The ASC web UI backs the same behavior with an explicit 3-way choice (Manually release this version / Automatically release this version / Automatically release this version after App Review, no earlier than); skipping releaseType in a scripted create/update leaves the version's release behavior to an undocumented default — in practice new versions show up as auto-release — instead of a decision your pipeline made on purpose. Default to MANUAL in automation unless auto-release is the deliberate intent.

Rationale

• No fastlane by default: spaceship drags a Ruby toolchain into a repo whose only Ruby consumer would be release tooling — against the catalog's mise/no-Homebrew baseline — and inserts a drift layer that breaks whenever ASC changes ahead of a spaceship release. Direct REST against Apple's own docs has zero intermediary.
• CryptoKit mint script: token minting is the only genuinely fiddly step (ES256, raw-signature format); everything after is plain curl. A 30-line Apple-native script beats installing PyJWT or hand-rolling openssl DER conversion.
• Least privilege: token-leak blast radius scales with the key's role; the scope claim can pin a single script to a single request.

Deviation considerations

• Already on fastlane with maintained lanes and a Gemfile → keep it; this skill is the default for repos without a Ruby toolchain, not a migration mandate.
• Heavy tooling (dozens of endpoints, typed models, retries) → generate a client from Apple's published App Store Connect OpenAPI spec instead of hand-rolled curl; still no fastlane required.
• One-off manual task → the ASC web UI is faster; scripting has a floor cost.

Common Mistakes

1. iss set to Team ID — ASC API wants the Issuer ID (UUID); Team ID belongs to other Apple JWTs (e.g. APNs). Symptom: 401 NOT_AUTHORIZED with a well-formed token.
2. exp more than 20 minutes ahead — token rejected outright; also watch local clock skew on iat.
3. openssl-signed tokens failing — openssl dgst emits a DER-encoded signature; JWT ES256 requires the raw 64-byte r‖s form. CryptoKit's rawRepresentation is already correct.
4. Uploading the binary via REST — no such endpoint exists; route builds through Xcode Cloud, local-archive-export-upload, Organizer, or Transporter.
5. Ignoring pagination — the default page size silently truncates; always limit=200 + follow links.next.
6. Parsing salesReports as JSON — it's a gzipped TSV file.
7. Tight-polling build processing or analytics without reading X-Rate-Limit — 429 locks out every consumer of the key.
8. Admin-role key in CI when App Manager or a scoped token suffices.
9. .p8 committed to the repo — stop and run the rotate-first SOP in apple-public-repo-security; storage layout per build-time-secret-injection.
10. Omitting releaseType on an appStoreVersions create/update — the attribute has no documented default, so an unset value can leave a version on automatic release; it goes live the instant Apple approves it instead of waiting for a deliberate manual release. Set releaseType: "MANUAL" explicitly unless auto-release is intended.

Review Checklist

• Team key with least-privilege role; .p8 + IDs stored per build-time-secret-injection Layer 2, nothing tracked by git
• Token claims: ES256, kid header, iss = Issuer ID (or sub: "user" for individual keys), exp ≤ 20 min, aud appstoreconnect-v1
• Every collection call sets limit and follows links.next
• 429 handled with backoff; no tight polling loops
• Write calls use the JSON:API {"data": {...}} wrapper
• No REST binary-upload attempt; build side delegated to xcode-cloud-single-track-ci
• releaseType explicitly set on every appStoreVersions create/update (MANUAL unless auto-release is intended) — never left to ASC's undocumented default
• grep for key IDs / issuer ID / .p8 contents across tracked files returns zero hits

Related skills

• xcode-cloud-single-track-ci — build & upload side; this skill starts after the build exists in ASC
• local-archive-export-upload — the local xcodebuild -exportArchive / altool upload path; this skill starts after the build exists in ASC
• build-time-secret-injection — where ASC_KEY_ID / ASC_ISSUER_ID / the .p8 live (Layer 2 secrets/.env)
• apple-public-repo-security — .p8 leak prevention and the rotate-first SOP
• app-store-review-rejections — what to submit so review passes; this skill is how to submit