Skip to main content
Apple Search Ads credentials are created in the Search Ads account, not in App Store Connect. A Search Ads API key gives Appeeky access to the campaigns and reports for the selected organization.
Apple Search Ads API keys are separate from App Store Connect API keys. A working App Store Connect key cannot be used for Search Ads campaigns.

​
Create a Search Ads API Key

  1. Sign in at searchads.apple.com.
  2. Open Account Settings > API or User Management > API. The label can vary by account layout.
  3. Generate an API client.
  4. Upload your public key. Apple expects an EC P-256 key pair, similar to App Store Connect.
  5. Save these values:
    • Client ID: usually starts with SEARCHADS.
    • Team ID: often the same value as Client ID
    • Key ID
    • Org ID: numeric Search Ads organization ID
    • Private key: .p8 PEM, shown or downloaded once
Apple’s reference: Implementing OAuth for the Apple Search Ads API.
Save the private key immediately. Apple may only show or download it once.

​
Connect Credentials

curl
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/credentials" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "teamId": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "keyId": "c60fc276-80a7-440d-b800-f13a7dcc6fde",
    "orgId": "21106140",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }'
FieldRequiredDescription
clientIdYesSearch Ads API client ID
teamIdYesSearch Ads team ID
keyIdYesAPI key ID
orgIdYesNumeric Search Ads organization ID
privateKeyYesEC private key PEM
Appeeky validates credentials against Apple before saving them. Saved credentials are stored securely and encrypted at rest.

​
Check Connection Status

curl
curl "https://api.appeeky.com/v1/connect/apple-ads/credentials/status" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
Example response: 
{
  "data": {
    "connected": true,
    "clientId": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "teamId": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "orgId": "21106140",
    "keyId": "c60fc276-80a7-440d-b800-f13a7dcc6fde",
    "lastVerifiedAt": "2026-06-09T12:00:00Z"
  }
}

​
Verify Account Access

​
Current API User

curl
curl "https://api.appeeky.com/v1/connect/apple-ads/me" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"

​
Accessible Organizations

curl
curl "https://api.appeeky.com/v1/connect/apple-ads/acls" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
Use /acls to confirm which Search Ads organizations the API key can access and which roles Apple assigned.

​
Disconnect

curl
curl -X DELETE "https://api.appeeky.com/v1/connect/apple-ads/credentials" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
This removes the saved Search Ads connection from Appeeky.

​
Authentication Options

​
Stored Credentials

Connect once with: 
POST /v1/connect/apple-ads/credentials
After that, data requests only need your Appeeky API key. This is recommended for production and for MCP tools.

​
Per-Request Headers

For one-off calls or tests, pass Search Ads credentials on every request:
HeaderRequiredDescription
X-ASA-Client-IdYesSearch Ads Client ID
X-ASA-Team-IdYesTeam ID
X-ASA-Key-IdYesAPI Key ID
X-ASA-Org-IdYesOrganization ID
X-ASA-Private-KeyYes*Private key PEM
X-ASA-Private-Key-B64Yes*Base64-encoded PEM alternative
* Provide either X-ASA-Private-Key or X-ASA-Private-Key-B64.
curl
curl "https://api.appeeky.com/v1/connect/apple-ads/campaigns" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-ASA-Client-Id: SEARCHADS.xxx" \
  -H "X-ASA-Team-Id: SEARCHADS.xxx" \
  -H "X-ASA-Key-Id: your-key-id" \
  -H "X-ASA-Org-Id: 21106140" \
  -H "X-ASA-Private-Key: -----BEGIN PRIVATE KEY-----..."

​
Plan Requirement

Apple Search Ads requires Indie plan or higher. If connection fails with PLAN_REQUIRED, upgrade the account or use an API key tied to an eligible Appeeky account.

​
Troubleshooting

ErrorMeaningFix
MISSING_FIELDSConnect body is missing required Search Ads fieldsSend clientId, teamId, keyId, orgId, and privateKey
INVALID_ASC_CREDENTIALSApple rejected the Search Ads OAuth credentialsRecreate the Search Ads API key and verify the org ID
ASA_CREDENTIALS_REQUIREDNo saved credentials and no X-ASA-* headersConnect credentials once or pass per-request headers
PLAN_REQUIREDAccount is not on an eligible planUse an eligible Appeeky account
Apple 403API key has no access to that organization or routeCheck Search Ads roles and /acls