Connect Apple Search Ads

Once Apple Search Ads is connected, your agent runs your App Store search ads the same way it runs the other eleven ad platforms: it builds the campaign, the ad group, the targeting keywords and the negatives, reads back what Apple actually stored, and reports performance down to the search term someone typed before they installed. Everything it creates is created paused, and enabling spend is a separate, explicitly confirmed step.

Connecting takes about five minutes. You will not run openssl, and no Apple password goes anywhere near Hermoso.

First, the thing that stops most people

Apple’s own instructions say: “From the Ads UI, choose Account Settings › API. Paste the key into the Public Key field.”

That field does not exist for an Account Admin. Sign in as the admin on your own account, open Account Settings › API, and what renders is a table headed Manage API Access — a list of third-party service providers with a single Remove Access action — and no key field anywhere on the page. It reads exactly like a missing feature, which is why people stop here and conclude the API is not available to them.

It is available. The Public Key field belongs to a user holding an API role, and being the account’s admin is not one. Apple’s invite dialog offers six roles, of which exactly two are API roles:

• API Account Manager — “read and write access to all campaign groups for API management”. This is the one to pick if you want Hermoso to build campaigns, not just report on them.
• API Account Read Only — “read only access to all campaign groups for API management”. Enough for reporting, and nothing else.

The other four — Account Admin, Account Finance, Account Read Only and Limited Access — cannot mint API credentials at all. So the fix is an invite you send to yourself:

1. Open Account Settings › User Management and choose Invite Users.
2. Invite an address you control — your own, or a shared one like [email protected] so the credential outlives any one person — with the role API Account Manager.
3. Accept the invitation from that inbox, then sign in to Apple Ads as that user.

Now Account Settings › API has a Public Key field on it.

The connection, step by step

1. Start it in Hermoso. Settings › Connectors › Apple Ads › Connect. Hermoso generates an EC P-256 signing key — the same prime256v1 key Apple’s two openssl commands would have produced — and shows you the public half only. Copy it.
2. Give the public half to Apple. As your API-role user, open Account Settings › API, paste it into Public Key, and Save.
3. Copy the three ids back. Apple now prints clientId, teamId and keyId above that field. All three.
4. Finish it in Hermoso. Paste the three ids and save. Hermoso exchanges a token with Apple and reads your organization list before it stores anything, so a mistyped id fails right there, while you can still see what you pasted — not at your first report an hour later.
5. Pick the organization, if your credentials cover more than one. The connection is pinned to the one you choose.

If something goes wrong

There is no Public Key field on the API page

You are signed in as an Account Admin, or as any of the four non-API roles. Invite yourself as an API Account Manager and sign in as that user — see above. This is the single most common reason an Apple Ads connection never gets made.

Apple rejects the credentials

The three ids have to belong to the key Apple is holding. Re-copy clientId, teamId and keyId from directly above the Public Key field — not from an older key you replaced. If they still fail, start the connection again in Hermoso: that mints a fresh key pair, and you paste the new public half into Apple.

The setup session expired

Hermoso holds the generated private key for 24 hours while you go and paste its public half into Apple. Past that it is gone, deliberately — start the connection again and paste the new public key.

I already generated a key with openssl

Then use it. Paste your existing EC P-256 private key when you connect instead of taking Hermoso’s, and the public key already sitting in your Apple account keeps working. It has to be an EC P-256 (prime256v1) key — Apple accepts no other curve.

I manage several Apple Ads organizations

Connect each one in its own Hermoso brand workspace. A connection is pinned to a single organization, which is what stops an agency’s campaign landing in the wrong client’s account.

What your agent can do once it is connected

Build: create_apple_ads_campaign, create_apple_ads_ad_group, add_apple_ads_keywords, add_apple_ads_negative_keywords, update_apple_ads_object, set_apple_ads_status, delete_apple_ads_object.

Read: list_apple_ads_campaigns (status, serving status, daily and total budget, the countries a campaign runs in, and Apple’s own stated reason when one cannot run), list_apple_ads_ad_groups (default bid, and whether Apple’s Search Match is on), list_apple_ads_keywords (targeting and negative, with match type and bid), apple_ads_report (impressions, taps, installs, spend, TTR, CPT and CPA at campaign, ad group, keyword, search-term or ad level) and list_apple_ads_orgs.

All of it is callable from Claude, Claude Code, Codex, Cursor, Cline, OpenClaw, Hermes or any other MCP client, and from the web studio — same engine either way. See the MCP overview or the ads tool reference.

Frequently asked

Why is there no Public Key field on the Apple Ads API page?

Because you are signed in as an Account Admin. Apple only renders that field for a user holding an API role. An admin sees a “Manage API Access” table of third-party service providers instead, with no key field anywhere on the page. Invite yourself as an API Account Manager under Account Settings › User Management, sign in as that user, and the field is there.

Which Apple Ads role do I need?

API Account Manager if you want Hermoso to build campaigns, ad groups and keywords — Apple describes it as “read and write access to all campaign groups for API management”. API Account Read Only is enough if you only want reporting. The other four roles Apple offers — Account Admin, Account Finance, Account Read Only and Limited Access — cannot mint API credentials at all.

Do I have to run openssl?

No. Apple’s own instructions hand you two openssl commands; Hermoso generates the EC P-256 key pair for you and shows you only the public half. The private half is what signs your requests, and you never see it, paste it or store it. If you already have a key from another tool you can bring it instead.

Does connecting Apple Ads cost anything or risk spend?

No. The reads are free to call, and every object Hermoso creates is created PAUSED with no override. Enabling an object is the only switch that arms real spend, and it takes an explicit confirmation.

What are clientId, teamId and keyId?

The three identifiers Apple prints above the Public Key field once you save your key. They identify your API user to Apple; the private key proves it is you. Paste all three back into Hermoso and the connection is done.

Can one connection cover several Apple Ads organizations?

One connection is pinned to the single organization you choose when you make it. Apple treats an orgId rather like a campaign group, so one login can cover several — an agency with a client per org connects each one in its own Hermoso brand workspace.

Do I have to rotate the key every 180 days?

No. Apple caps a client secret at 180 days, which is why its own instructions have you diary a rotation. Hermoso holds the private key and mints a fresh short-lived secret for each token exchange, so there is nothing sitting in a config file to expire.