App Store Connect

When to Use

User needs to manage iOS/macOS apps on App Store Connect. Agent handles API authentication, build management, TestFlight distribution, App Review submissions, and analytics retrieval.

Quick Reference

Core Rules

1. JWT Authentication Required

App Store Connect API uses JWT tokens signed with your private key.

# Required environment variables:
# ASC_ISSUER_ID     - From App Store Connect > Users > Keys
# ASC_KEY_ID        - From the API key you created
# ASC_PRIVATE_KEY_PATH - Path to your .p8 private key file

Generate JWT with ES256 algorithm, 20-minute expiration max. See api-auth.md for code examples.

2. API Versioning

Always specify API version in requests.

curl -H "Authorization: Bearer $JWT" \
     "https://api.appstoreconnect.apple.com/v1/apps"

Current stable version: v1. Check Apple docs for v2 endpoints.

3. Build Processing States

Builds go through states after upload:

Never submit a build that is not VALID.

4. TestFlight Distribution

• Internal Testing: Up to 100 members, builds available immediately after processing
• External Testing: Up to 10,000 testers, requires Beta App Review for first build of version
• External groups need at least: app description, feedback email, privacy policy URL

5. App Review Submission

Before submitting for review:

• All required metadata complete (descriptions, keywords, screenshots)
• App Preview videos under 30 seconds
• Privacy policy URL valid and accessible
• Contact information current

Submission creates an appStoreVersion in PENDING_DEVELOPER_RELEASE or WAITING_FOR_REVIEW.

6. Rate Limits

API has rate limits per hour. Handle 429 responses with exponential backoff.

# Respect Retry-After header
HTTP/1.1 429 Too Many Requests
Retry-After: 60

7. Bundle ID Management

Bundle IDs are permanent once created. Cannot be deleted or renamed.

• Use reverse-domain notation: com.company.appname
• Plan naming carefully before registration
• Each bundle ID can only belong to one team

Common Traps

• Expired JWT - Tokens expire in 20 min max. Regenerate before long operations.
• Wrong key permissions - API keys need specific roles (Admin, App Manager, etc.)
• Missing export compliance - Apps with encryption need ECCN or exemption documentation
• Build version collision - Each build needs unique version+build number combo
• Screenshot dimensions - Must match exactly for each device type (no scaling)
• Phased release confusion - Phased release is for App Store only, not TestFlight