All docs
Connect

Apple Ads: connect with a key pair, then manage campaigns and reports

TL;DR

Apple Ads signs in with a private key and three ids. Agent Planners can generate the key pair for you — the private key stays encrypted on our server and you copy only the public key into Apple Ads — or you can paste your own. The connection is checked with Apple before it is saved.

What you need

  • An Apple Ads account (ads.apple.com) and someone who can invite users to it — an account administrator.
  • An API user: a user invited with an API role. API Account Manager lets the agent make changes; API Account Read Only lets it only read.
  • A key pair. Apple identifies the API user by a public key you upload. Agent Planners makes one for you, or you bring your own private key (an EC P-256 key in PEM form).
  • Three ids Apple shows after the key is saved: the Client ID and Team ID (each starts with SEARCHADS.) and the Key ID.

Connect step by step

  1. 1In Agent Planners open Integrations → Apple Ads → Generate a key for me and copy the public key. (Or choose I already have a private key and paste it — it is stored encrypted and never shown again.)
  2. 2In Apple Ads, the administrator opens Account Settings → User Management → Invite Users and invites the API user with API Account Manager or API Account Read Only.
  3. 3The API user accepts, signs in to Apple Ads, opens Account Settings → API, pastes the public key into Public Key and clicks Save.
  4. 4Apple shows the Client ID, Team ID and Key ID. Paste them on the Apple Ads card and press Connect.
  5. 5Agent Planners signs in to Apple once, lists the ad accounts the API user reaches and saves one connection per ad account. If Apple refuses, the card says which id or role to check.
Apple's sign-in uses a token that lasts an hour; Agent Planners renews it before it ends and re-signs its own client secret before that expires, so nothing needs to be re-entered.

Before campaigns can serve

  • A payment method on file. An account without one answers INACTIVE (Apple's reason ORG_NO_PAYMENT_METHOD_ON_FILE) — the agent reads and plans, but nothing serves.
  • An app the account may promote. A campaign promotes an App Store app the account has access to; the card and the agent's account-health read say when it is missing.
  • Delivery is yours to turn on. Everything the agent creates starts paused.

What the agent can do

  • 12 reads and 14 writes on the Apple Ads Platform API (Apple's current API; the older Campaign Management API v5 shuts down on 2027-01-26).
  • Reads: ad accounts, campaigns, ad groups, keywords, negative keywords, ads, account health, and App Store reports by campaign, ad group, ad, keyword or search term in the account's time zone.
  • Changes: paused campaigns and ad groups, keywords and negative keywords, keyword bids and statuses, names and schedules, pausing, and other documented writes through one gateway.
  • Previews: every change can be previewed first. Apple's API has no validate-only mode, so a preview is the exact request that would be sent, not Apple's verdict.

What needs a person

  • By default every change waits for your approval card; auto-approve and an API key that applies changes at once are opt-in.
  • Always a person, on every lane: turning anything on (status ENABLED), a daily budget or bid-strategy change, an ad group's bid change, and deleting a campaign or ad group.
  • Refused: money in micros or cents, a status other than ENABLED or PAUSED, another ad account, and account administration — budget orders, users and permissions stay in Apple Ads.

Frequently asked questions

Do I need to keep a key file on my computer?
No. If Agent Planners generates the key pair, the private key lives only on our server, encrypted, and you copy just the public key into Apple Ads.
Which role should the API user have?
API Account Manager if the agent should make changes, API Account Read Only if it should only read. Apple's role decides what the API user can do; Agent Planners' approvals come on top.
Why is my account INACTIVE?
Apple marks an ad account INACTIVE when, for example, it has no payment method on file. Add one in Apple Ads; the agent's account-health read gives Apple's own reason.

Related