> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Apple Search Ads Credentials
> Generate a Search Ads API key, connect credentials, verify org access, and choose stored or per-request authentication
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](https://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](https://developer.apple.com/documentation/apple_search_ads/implementing_oauth_for_the_apple_search_ads_api).
Save the private key immediately. Apple may only show or download it once.
***
## Connect Credentials
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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-----"
}'
```
| Field | Required | Description |
| ------------ | -------- | ---------------------------------- |
| `clientId` | Yes | Search Ads API client ID |
| `teamId` | Yes | Search Ads team ID |
| `keyId` | Yes | API key ID |
| `orgId` | Yes | Numeric Search Ads organization ID |
| `privateKey` | Yes | EC private key PEM |
Appeeky validates credentials against Apple before saving them. Saved credentials are stored securely and encrypted at rest.
***
## Check Connection Status
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/apple-ads/credentials/status" \
-H "X-API-Key: YOUR_APPEEKY_KEY"
```
Example response:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/apple-ads/me" \
-H "X-API-Key: YOUR_APPEEKY_KEY"
```
### Accessible Organizations
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
| Header | Required | Description |
| ----------------------- | -------- | ------------------------------ |
| `X-ASA-Client-Id` | Yes | Search Ads Client ID |
| `X-ASA-Team-Id` | Yes | Team ID |
| `X-ASA-Key-Id` | Yes | API Key ID |
| `X-ASA-Org-Id` | Yes | Organization ID |
| `X-ASA-Private-Key` | Yes\* | Private key PEM |
| `X-ASA-Private-Key-B64` | Yes\* | Base64-encoded PEM alternative |
\* Provide either `X-ASA-Private-Key` or `X-ASA-Private-Key-B64`.
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
| Error | Meaning | Fix |
| -------------------------- | --------------------------------------------------- | ------------------------------------------------------------- |
| `MISSING_FIELDS` | Connect body is missing required Search Ads fields | Send `clientId`, `teamId`, `keyId`, `orgId`, and `privateKey` |
| `INVALID_ASC_CREDENTIALS` | Apple rejected the Search Ads OAuth credentials | Recreate the Search Ads API key and verify the org ID |
| `ASA_CREDENTIALS_REQUIRED` | No saved credentials and no `X-ASA-*` headers | Connect credentials once or pass per-request headers |
| `PLAN_REQUIRED` | Account is not on an eligible plan | Use an eligible Appeeky account |
| Apple 403 | API key has no access to that organization or route | Check Search Ads roles and `/acls` |