Skip to main content
Pricing, subscriptions, and availability Level: Intermediate 11 min read

Individual vs Team API Key Restrictions on Sales and Financial Endpoints

Why Apple restricts Individual API keys from accessing sales and financial reporting endpoints, how Team API keys resolve HTTP 403 Forbidden errors, and what FlightDeck can diagnose.

Published: 2026-11-03 • Last Updated: 2026-11-03 • Author: Kip Lawrence
Key MCP Tools: apps_listreports_sales_and_finance_summaryflightdeck_execute_operation

Overview: The Anatomy of Apple API Key Restrictions

When developers configure AI coding assistants or automated continuous integration tools to query App Store Connect, one of the most frustrating obstacles is encountering an unexpected HTTP 403 Forbidden error when requesting sales numbers or downloading financial reports. The API key appears valid, metadata queries succeed, and TestFlight builds list normally—yet calling sales endpoints fails completely.

The root cause lies in Apple's Identity and Access Management (IAM) architecture. In App Store Connect, API keys are divided into two distinct categories: Team API Keys and Individual API Keys.

While both key types use JSON Web Tokens (JWT) signed with ES256 private keys (.p8), Apple enforces strict security and organizational boundaries around who can generate them, what permissions they inherit, and which API resource endpoints they are legally permitted to touch.

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   APPLE API KEY ACCESS & BOUNDARY MATRIX               │
├───────────────────────────────┬───────────────────┬────────────────────┤
│ Capability / Endpoint         │ Team API Key      │ Individual API Key │
├───────────────────────────────┼───────────────────┼────────────────────┤
│ Metadata & App Versions       │ YES (Role-based)  │ YES                │
│ TestFlight & Beta Groups      │ YES (Role-based)  │ YES                │
│ Xcode Cloud & Builds          │ YES (Role-based)  │ YES                │
│ Sales Reports (/v1/salesReports) | YES (Admin/Finance)| NO (Blocked)   │
│ Finance Reports (/v1/financeReports) | YES (Admin/Finance)| NO (Blocked)│
│ Provisioning & Certificates   │ YES (Admin/Dev)   │ NO (Blocked)       │
│ Notarization (notarytool)     │ YES               │ NO (Blocked)       │
│ Issuer ID Header (iss)        │ Organization UUID │ sub: "user"        │
└───────────────────────────────┴───────────────────┴────────────────────┘

Apple explicitly bars Individual API keys from accessing sales and financial reporting endpoints because financial proceeds, settlement reports, and banking remittances represent legal entity records belonging to the entire developer organization, rather than an individual contributor.


The Primary Sales & Key Inspection Prompt

Use this prompt with your AI coding assistant (Cursor, Claude Code, Windsurf, or Roo Code) connected to FlightDeck to inspect your current key configuration and verify your reporting capabilities:

TEXT
Inspect my active App Store Connect connection profile. Determine whether I am authenticated using a Team API Key or an Individual API Key. Check if my key has the required permissions to retrieve sales and financial summaries, and report any configuration issues preventing report access.

Why Apple Restricts Individual API Keys

To understand why Apple enforces this restriction, you must examine how developer accounts and credentials are structured.

1. Personal vs. Organizational Scope

  • Individual Developer Accounts: Belong to a single human being registered as an individual. While this developer is both the Account Holder and the sole operator, API keys generated under their individual user account remain classified as Individual Keys unless generated through the organization-wide Team API Key interface.
  • Organization Developer Accounts: Belong to a corporation, LLC, partnership, or non-profit institution. Multiple team members hold specific roles (Account Holder, Admin, Finance, App Manager, Developer, Marketing, Sales).

Financial reports (GET /v1/financeReports) detail monthly wire transfer proceeds, tax withholding schedules, currency conversion rates, and regional banking distributions. Sales reports (GET /v1/salesReports) expose aggregate customer purchase volumes across all apps in the account. Apple restricts access to users and credentials that hold an explicit Finance or Admin role at the organization level. Individual keys do not carry organization-level role delegations.

3. Provisioning and Notarization Restrictions

In addition to financial endpoints, Apple bars Individual API keys from:

  • Device provisioning profiles, bundle IDs, and certificate signing requests (/v1/certificates, /v1/bundleIds, /v1/profiles).
  • Command-line notarization via xcrun notarytool.

Attempting to invoke these restricted endpoints with an Individual API key triggers an immediate authorization rejection from Apple's edge gateways before any data processing begins.


Anatomy of the Authorization Failure: HTTP 401 vs. HTTP 403

When diagnosing API failures in AI agents or CLI scripts, distinguishing between HTTP 401 and HTTP 403 is critical:

HTTP 401 Unauthorized

The authentication token is malformed, expired, or cryptographically invalid:

  • The private key (.p8) does not match the Key ID specified in the token header (kid).
  • The token expiration timestamp (exp) exceeds the 20-minute maximum permitted by Apple.
  • The token issue timestamp (iat) is set in the future due to local system clock skew.
  • The Issuer ID (iss) is invalid or incorrectly formatted.

HTTP 403 Forbidden

The authentication token is cryptographically valid, but Apple refuses to fulfill the request due to authorization or agreement constraints. A typical Apple error payload resembles:

JSON
{
  "errors": [
    {
      "status": "403",
      "code": "FORBIDDEN_ERROR",
      "title": "The request is forbidden for the current authentication credentials.",
      "detail": "This resource is not available for the authenticated entity or role."
    }
  ]
}

An HTTP 403 Forbidden response on /v1/salesReports or /v1/financeReports does not arise from a single cause. It requires a systematic diagnostic workflow to identify the specific gating factor:

  1. Authentication Scope (Key Type): The request was signed with an Individual API Key (which lacks an Organization Issuer ID iss). Apple explicitly blocks Individual API keys from sales and finance endpoints.
  2. Role Authorization (Key Permissions): The request used a Team API Key, but the key's assigned role is Developer, App Manager, or Marketing, rather than Finance or Admin.
  3. Legal Agreement Prerequisites: The developer organization has not accepted or updated the Paid Applications Agreement (Schedule 2) in App Store Connect under Business. Financial reporting remains locked until Schedule 2 is active.
  4. Vendor Number Mismatch: The requested filter[vendorNumber] parameter does not match the 8-digit vendor number assigned to your account, or the authenticated key lacks access to that vendor entity.
  5. Account Standing: The Apple Developer Program membership has expired or is under administrative hold.

What FlightDeck Can and Cannot Do

To maintain security and transparency, recognize the clear division between FlightDeck MCP tooling and Apple's administrative portals:

What FlightDeck MCP Can Do

  1. Detect Key Type and Profile: FlightDeck reads your configured connection profile from the local macOS Keychain and identifies whether the active profile specifies an Issuer ID (Team Key) or personal user credentials.
  2. Retrieve and Summarize Complete Reports: When backed by a valid Team API Key with Finance or Admin role, FlightDeck's reports_sales_and_finance_summary tool retrieves, decompresses, and aggregates sales and financial TSV data with exact decimal arithmetic without context truncation.
  3. Execute Raw Operations: The flightdeck_execute_operation dispatcher safely invokes salesReports_getCollection and financeReports_getCollection while enforcing response decompression and security redacting.
  4. Surface Actionable Diagnostics: Catches HTTP 403 errors and clearly informs the agent whether the blocker is key type or role permissions.

What Must Be Done in Apple's Web Portal

  1. Generating Team API Keys: FlightDeck cannot create or download .p8 private keys. The Account Holder or Admin must log into App Store Connect and generate Team Keys manually.
  2. Assigning Roles: Role assignment (e.g., granting the Finance role) is governed strictly within the App Store Connect web interface under Users and Access.
  3. Accepting Agreements: If the Paid Applications Agreement is expired or unaccepted, sales reporting endpoints may remain inaccessible regardless of key permissions.

Step-by-Step Workflow: Migrating to a Team API Key

To enable financial and sales reporting capabilities in FlightDeck, follow this migration process:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   TEAM API KEY SETUP & ROLES WORKFLOW                  │
│                                                                        │
│   1. SIGN IN TO APP STORE CONNECT WEB PORTAL                           │
│   [Navigate to Users and Access > Integrations > Team Keys]            │
│                            │                                           │
│                            ▼                                           │
│   2. GENERATE NEW TEAM API KEY                                         │
│   [Assign 'Admin' or 'Finance' role; download AuthKey_XXXXXXXXXX.p8]   │
│                            │                                           │
│                            ▼                                           │
│   3. RECORD ISSUER ID & KEY ID                                         │
│   [Copy Issuer ID UUID and alphanumeric 10-character Key ID]           │
│                            │                                           │
│                            ▼                                           │
│   4. CONFIGURE FLIGHTDECK DESKTOP CONNECTION PROFILE                   │
│   [Store credentials safely in hardware-backed macOS Keychain]         │
│                            │                                           │
│                            ▼                                           │
│   5. AUDIT REPORT ACCESS VIA MCP                                       │
│   [Run reports_sales_and_finance_summary to verify HTTP 200]           │
└────────────────────────────────────────────────────────────────────────┘

Step 1: Generate a Team API Key in App Store Connect

  1. Sign in to App Store Connect as Account Holder or Admin.
  2. Click Users and Access, then select the Integrations tab (formerly Keys).
  3. Ensure Team Keys is selected in the sidebar.
  4. Click the + (Generate API Key) button.
  5. Enter a descriptive name (e.g., FlightDeck Automation Key).
  6. Select the Finance role (or Admin if this key will also manage builds, versions, and app submissions).
  7. Click Generate.
  8. Copy the Issuer ID displayed near the top of the page.
  9. Locate your newly generated key, copy the 10-character Key ID, and click Download API Key (AuthKey_XXXXXXXXXX.p8).
Important

Apple permits downloading the .p8 private key file exactly once. Store it in a secure location. FlightDeck encrypts and stores the key material directly in your local hardware-backed macOS Keychain.

Step 2: Configure the Profile in FlightDeck Desktop

  1. Open the FlightDeck desktop application.
  2. Navigate to Settings > Profiles.
  3. Click Add Profile and choose App Store Connect Team Key.
  4. Enter the Key ID, paste the Issuer ID UUID, and select the downloaded AuthKey_XXXXXXXXXX.p8 file.
  5. Save the profile. FlightDeck verifies the key against Apple's /v1/apps endpoint to confirm token signing validity.

Step 3: Verify Report Capabilities with Your AI Assistant

Run this verification prompt in your IDE:

TEXT
Run a test query on sales reports for vendor number [YOUR_8_DIGIT_VENDOR_NUMBER] for yesterday's date. Confirm that the request succeeds with HTTP 200 and return a summary of total downloads and sales by currency.

If configured correctly, reports_sales_and_finance_summary returns structured JSON aggregates partitioned by currency and product type.


Common Errors & Troubleshooting

1. 403 FORBIDDEN_ERROR: Key Type / Scope

  • Cause: Active profile uses an Individual API Key without an Issuer ID (iss).
  • Fix: Generate a Team API Key in App Store Connect under Users and Access > Integrations > Team Keys and configure a Team profile in FlightDeck Desktop.

2. 403 FORBIDDEN_ERROR: Insufficient Role

  • Cause: Team API Key was generated with Developer, Marketing, or App Manager role rather than Finance or Admin.
  • Fix: Team key roles are immutable after generation. Delete the key in App Store Connect and generate a replacement with the Finance (or Admin) role.

3. 403 FORBIDDEN_ERROR: Inactive Paid Applications Agreement

  • Cause: The organization has not executed or updated Schedule 2 (Paid Applications Agreement) under App Store Connect > Business.
  • Fix: Have the Account Holder sign into App Store Connect and accept any pending agreements or amendments in the Business module.

4. 400 / 403: Vendor Number Mismatch or Invalid Parameter

  • Cause: Querying reports_sales_and_finance_summary with an incorrect 8-digit vendor number, an App ID, or a vendor number from another legal entity.
  • Fix: Retrieve the exact numeric vendor number from App Store Connect > Business > Reports (displayed in the top selector).

5. 401 UNAUTHORIZED: Token Expiration or Clock Skew

  • Cause: Local system clock skew exceeds Apple's 20-minute JWT validity window, or .p8 key does not match Key ID.
  • Fix: Synchronize local system time with Apple Network Time (time.apple.com) and verify Key ID matches the downloaded file name.


Official References


Evidence Limitations & Verifications

  • L1 Official Documentation Verification: Key scope restrictions, role requirements (Admin/Finance), and reporting parameters verified against Apple App Store Connect API documentation and OpenAPI specification (openapi.oas.json).
  • L2 Codebase Source Inspection: Code inspection of FlightDeck's asc_mcp_server.dart, AscClient, and reports_sales_and_finance_summary confirms report decompression and exact decimal aggregation.
  • Diagnostic Scope Notice: HTTP 403 Forbidden is a gateway response that can indicate key scope, role insufficiency, unaccepted agreements, or vendor mismatch; developers should follow the diagnostic checklist above to identify the specific gating factor.

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store