app-store-connect-api

name: app-store-connect-api description: > Guide for implementing Apple App Store Connect API integrations. Use when: (1) Building API clients to manage certificates, provisioning profiles, bundle IDs, or devices, (2) Implementing JWT authentication for App Store Connect, (3) Understanding API request/response patterns and error handling, (4) Working with TestFlight builds, beta groups, or app submissions, (5) Discovering available endpoints, schemas, or capabilities via the OpenAPI spec. Includes scripts for fetching and analyzing Apple's official OpenAPI specification.

App Store Connect API Development

Quick Reference

Base URL: https://api.appstoreconnect.apple.com/
Auth: JWT with ES256 signature (max 20 min lifetime)
Format: JSON:API specification

Authentication

Generate JWT with these claims:

{
  "iss": "ISSUER_ID",      // From App Store Connect
  "iat": <unix_timestamp>,
  "exp": <iat + 1200>,     // Max 20 minutes
  "aud": "appstoreconnect-v1"
}

Header: { "alg": "ES256", "kid": "KEY_ID", "typ": "JWT" }

For code examples in C#, Python, Node.js, Go → see references/authentication.md

Request/Response Format

All resources follow JSON:API structure:

// Response
{
  "data": { "type": "bundleIds", "id": "ABC123", "attributes": {...} },
  "included": [...],  // Related resources when using ?include=
  "links": { "self": "...", "next": "..." }
}

// Create/Update Request
{
  "data": {
    "type": "bundleIds",
    "attributes": { "name": "My App", "identifier": "com.example.app", "platform": "IOS" },
    "relationships": { ... }
  }
}

Common query parameters:

filter[field]=value - Filter results
sort=field / sort=-field - Sort ascending/descending
limit=50 - Pagination (follow links.next)
include=relatedResource - Include related data
fields[type]=field1,field2 - Sparse fieldsets

For full patterns → see references/patterns.md

Core Resources

Resource	Endpoint	Key Operations
Certificates	`/v1/certificates`	List, Create (CSR), Delete
Bundle IDs	`/v1/bundleIds`	List, Create, Update name, Delete
Capabilities	`/v1/bundleIdCapabilities`	Enable, Update, Disable
Devices	`/v1/devices`	List, Register, Update status
Profiles	`/v1/profiles`	List, Create, Delete
Apps	`/v1/apps`	List, Get, Update
Builds	`/v1/builds`	List, Get, Update (expire)

For detailed schemas and request formats → see references/resources.md

Common Enums

Platform: IOS, MAC_OS, UNIVERSAL

CertificateType: IOS_DEVELOPMENT, IOS_DISTRIBUTION, MAC_APP_DEVELOPMENT, MAC_APP_DISTRIBUTION, DEVELOPER_ID_APPLICATION

ProfileType: IOS_APP_DEVELOPMENT, IOS_APP_STORE, IOS_APP_ADHOC, MAC_APP_DEVELOPMENT, MAC_APP_STORE

CapabilityType: PUSH_NOTIFICATIONS, ICLOUD, GAME_CENTER, IN_APP_PURCHASE, APP_GROUPS, APPLE_PAY, ASSOCIATED_DOMAINS, HEALTHKIT, HOMEKIT, SIRIKIT

Discovering Endpoints & Schemas

Use the OpenAPI spec analyzer script to explore the full API:

# Download spec and show summary
./scripts/fetch_openapi_spec.ps1

# List all 192 resource categories
./scripts/fetch_openapi_spec.ps1 -ListResources

# Show endpoints for a resource
./scripts/fetch_openapi_spec.ps1 -Resource BundleIdCapabilities

# Show schema details
./scripts/fetch_openapi_spec.ps1 -Schema BundleIdCreateRequest

# Search endpoints and schemas
./scripts/fetch_openapi_spec.ps1 -Search testflight

The script caches the spec at ~/.cache/asc-openapi/openapi.oas.json. Use -Refresh to re-download.

Error Handling

All errors return:

{
  "errors": [{
    "status": "400",
    "code": "PARAMETER_ERROR.INVALID",
    "title": "...",
    "detail": "..."
  }]
}

Common codes:

PARAMETER_ERROR.INVALID / PARAMETER_ERROR.MISSING - Bad request
NOT_FOUND - Resource doesn't exist
FORBIDDEN - Insufficient API key permissions
AUTHENTICATION_ERROR - JWT issues (expired, bad signature)
429 - Rate limited (check Retry-After header)

Implementation Tips

Token caching: Generate one token and reuse for ~15 min (leave buffer before 20 min expiry)
Pagination: Always follow links.next until exhausted; don't assume result counts
Relationship endpoints: Use /v1/bundleIds/{id}/bundleIdCapabilities not filter params (some relationships don't support filtering)
Wildcard bundle IDs: End with .* (e.g., com.example.*); have limited capability support
Profile devices: Development profiles require explicit device list; App Store profiles don't include devices
Certificate CSR: Generate locally with openssl or programmatically; submit base64-encoded content