Overview: Choosing the Right Apple API Key Type
When connecting an AI coding assistant (like Cursor, Claude Code, or Antigravity) to Apple's App Store Connect API through FlightDeck, you must authenticate programmatic requests using an App Store Connect API key.
Apple provides two distinct classes of API keys in App Store Connect: Team API Keys and Individual API Keys. While both use Elliptic Curve cryptography (ES256) and .p8 private key files, their permissions, architectural capabilities, and setup requirements differ substantially.
Understanding these differences is essential to configuring automated tooling securely without running into unexpected permission blocks or compromised developer credentials.
This guide explains the technical differences between Team and Individual keys, maps out their functional capabilities, outlines how FlightDeck manages API key security, and provides a step-by-step setup walkthrough.
Architectural Comparison: Team Keys vs. Individual Keys
In App Store Connect, API keys authenticate programmatic requests by signing short-lived JSON Web Tokens (JWTs). How Apple evaluates the permissions granted to that token depends entirely on whether it was generated at the team or individual level:
┌───────────────────────────────────────────────────────────┐
│ Apple Developer Program Account │
└─────────────────────────────┬─────────────────────────────┘
│
┌────────────────────┴────────────────────┐
▼ ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Team API Keys │ │ Individual API Keys │
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ • Created at Organization level │ │ • Created under personal profile│
│ • Requires Issuer ID (UUID) │ │ • No Issuer ID (sub: "user") │
│ • Key ID + .p8 private key │ │ • Key ID + .p8 private key │
│ • Scoped by organizational role │ │ • Inherits personal user rights │
│ • Access to Provisioning APIs │ │ • BLOCKED from Provisioning APIs│
│ • Supports notarytool & CI/CD │ │ • BLOCKED from notarytool │
│ • Multiple keys supported │ │ • Strictly 1 key per user │
└─────────────────────────────────┘ └─────────────────────────────────┘
1. Team API Keys (Recommended for FlightDeck & AI Workflows)
Team API Keys are generated in App Store Connect under Users and Access > Integrations > Team Keys:
- Credentials Required:
- Key ID (
kid): A 10-character alphanumeric string (e.g.,2X9R4HXF34). - Issuer ID (
iss): A 36-character UUID identifying your Apple Developer organization (e.g.,57246542-96fe-1a63-e053-0824d011072a). - Private Key File (
.p8): An elliptic curve private key (PKCS#8 PEM format) downloadable exactly once from Apple. - Permission Model: Assigned a specific organizational role (e.g., Admin, App Manager, Developer, or Finance). Team keys apply across all apps in the account; Apple does not allow restricting a team key to individual apps.
- Endpoint Capabilities: Full access to all REST endpoints permitted by the selected role, including Provisioning APIs (managing certificates, bundle identifiers, and device profiles), TestFlight beta distribution, and app store submissions.
- Tooling Compatibility: Supported by Apple's
notarytoolfor macOS software notarization, Fastlane, Xcode Cloud, and FlightDeck.
2. Individual API Keys
Individual API Keys are generated under Users and Access > Integrations > Individual Keys (or directly on a user's personal profile):
- Credentials Required:
- Key ID (
kid): A 10-character alphanumeric string. - Private Key File (
.p8): Downloaded once. - No Issuer ID: Individual key JWTs use
sub: "user"in the token claims instead of an organizationalissUUID. - Permission Model: Inherits whatever permissions the individual developer has on the team.
- Key Limit: Apple strictly limits each user account to at most one active Individual API Key.
- Apple Restrictions: Individual keys are intentionally restricted by Apple:
- No Provisioning APIs: Cannot create or query certificates, bundle IDs, or provisioning profiles.
- No Notarytool: Cannot be used with Apple's
notarytoolcommand-line utility. - No Sales and Financial Reports: Restricted from downloading organizational financial data.
Feature Comparison Matrix
| Capability | Team API Key | Individual API Key |
|---|---|---|
| Primary Scope | Developer Organization / Team | Individual Developer Profile |
Issuer ID (iss) |
Required (UUID format) | Not Applicable (sub: "user") |
| Max Keys per Organization | Multiple (up to 50 active keys) | 1 key per individual user account |
| Role Customization | Configured per key (Admin, App Manager, Developer) | Inherits user's personal account role |
| Provisioning APIs (Certs, Profiles) | Supported (with Developer or Admin role) | Blocked by Apple |
Apple notarytool Notarization |
Supported | Blocked by Apple |
| Sales & Financial Reports | Supported (with Finance role) | Blocked by Apple |
| TestFlight Beta Distribution | Supported | Supported |
| App Store Version Metadata | Supported | Supported |
| FlightDeck Compatibility | Supported (Recommended) | Supported (Subject to Apple Restrictions) |
API Keys Are Not Code Signing Certificates: An App Store Connect API Key (.p8) cannot sign iOS binaries or assemble .ipa archives. It is strictly used to authenticate HTTP REST requests to Apple's management servers. Binary code signing requires an Apple Distribution Certificate (.p12 or Keychain identity) and a provisioning profile.
How FlightDeck Secures and Signs Your API Keys
FlightDeck connects your AI coding assistant (Cursor, Claude Code, Windsurf, Roo Code) to App Store Connect. Its profile manager supports both Team Keys and Individual Keys:
- Hardware-Backed Keychain Storage: FlightDeck encrypts and stores your
.p8private key directly in the macOS Keychain (AppleKeychainStorage). The key is never written to disk in unencrypted JSON, logged in plain text, or uploaded to any third-party cloud. - Apple-Conformant Token Signing: Whenever an agent queries FlightDeck, FlightDeck's native engine generates an in-memory JSON Web Token (JWT) signed with
ES256: - For Team Keys: The payload includes the organizationaliss(Issuer ID UUID), with nosubclaim. - For Individual Keys: The payload includessub: "user", with noissclaim. - Both token types specifyaud: "appstoreconnect-v1"and expire automatically within 20 minutes (Apple's required ceiling). - Multi-Account Profile Isolation: FlightDeck allows you to store multiple keys (e.g., Personal vs. Company accounts) and seamlessly switch between them using named profiles.
Practical Consequences of Using Individual Keys in FlightDeck:
While FlightDeck supports configuring Individual Keys (Supported (Subject to Apple Restrictions)), Team Keys are strongly recommended. If an AI agent or workflow attempts to manage Provisioning resources (certificates, bundle identifiers, device profiles) or retrieve financial reports using an Individual Key profile, Apple's servers will immediately reject the request with HTTP 403 Forbidden. Core app management, metadata updates, and TestFlight operations function normally within the developer's assigned individual permissions.
Step-by-Step: Generating and Configuring a Team API Key
Step 1: Generate the Team Key in App Store Connect
- Sign in to App Store Connect with an Account Holder or Admin account.
- Select Users and Access from the top navigation bar.
- Click the Integrations tab, then select Team Keys (under App Store Connect API).
- Click the blue + button.
- In the dialog, provide a descriptive name (e.g.,
FlightDeck AI Console) and choose the appropriate access role: - App Manager: Recommended for general release workflows, TestFlight management, and metadata updates. - Admin: Required if your agent needs to manage certificates, provisioning profiles, or user access. - Click Generate.
- Locate the newly created key in the list: - Copy the Issuer ID displayed at the top of the page. - Copy the Key ID shown in the table row. - Click Download API Key to download the
AuthKey_<KeyID>.p8file.
You can download the .p8 file only once. Store it in a secure location immediately. If you lose the file, you must revoke the key and generate a new one. Remember that Apple does not permit editing an API key's role after creation.
Step 2: Configure FlightDeck Desktop
- Launch FlightDeck on your Mac.
- Open Settings > Apple API Profiles.
- Click Add Profile: - Profile Name: Enter a label (e.g.,
Production Team). - Issuer ID: Paste the UUID copied from App Store Connect. - Key ID: Paste the 10-character alphanumeric Key ID. - Private Key: Click Browse and select your downloadedAuthKey_<KeyID>.p8file. - Click Test Connection & Save. FlightDeck validates the key, stores it in your macOS Keychain, and sends a test request to Apple.
Verifying Connection and Profile Status via AI
Once your profile is saved in FlightDeck and the MCP server is running, verify the connection from your connected AI coding assistant without manually assembling API requests or exposing secrets:
Verification Prompt
Copy and paste this prompt into Cursor, Claude Code, or Antigravity:
Using FlightDeck, check which App Store Connect profile is currently active, verify our authentication status, and list our registered applications without making changes.
What the AI Assistant Does
- The assistant queries FlightDeck's read-only application capability.
- FlightDeck authenticates the request using the active profile's credentials from the macOS Keychain.
- The assistant presents a clear confirmation:
Connected to App Store Connect via FlightDeck.
Active Profile: Production Team (Team Key)
Authentication Status: Valid (ES256 JWT minted successfully)
Registered Applications:
1. FlightDeck Developer Console (com.vibe.flightdeck)
2. TaskFlow Pro (com.example.taskflow)
Ready for TestFlight, metadata, and release operations.
If your assistant lists your registered apps, your authentication setup is complete.
Troubleshooting Common Authentication Failures
1. HTTP 401 Unauthorized
- Symptom: FlightDeck reports authentication failure when connecting to Apple.
- Root Causes:
- Mismatched Key ID or Issuer ID: Ensure the Key ID matches the filename (
AuthKey_<KeyID>.p8) and that the Issuer ID UUID contains no extraneous spaces. - Clock Drift: Apple enforces strict timestamp checks on JWT tokens (
iatandexp). Verify your Mac's clock is synchronized automatically via Apple network time in macOS System Settings. - Revoked Key: Confirm the key is still listed as active in App Store Connect.
2. HTTP 403 Forbidden
- Symptom: Authentication succeeds, but specific operations fail with HTTP 403.
- Root Causes:
- Individual Key Restrictions: You are using an Individual Key and attempted an operation blocked by Apple (such as querying Provisioning APIs or downloading financial reports).
- Role Limitation: Your Team Key has the Developer role, which prevents updating storefront metadata or submitting apps for review. To resolve, revoke the key and generate a new one with the App Manager or Admin role.