Skip to main content
You connect Apple Ads to Qonversion in the Qonversion dashboard under Settings → Connections → Apple Ads by selecting Connect with Apple: you sign in with Apple, choose the Apple Ads account and grant access; no private API key needs to be created or uploaded. Only a member with the Owner or Administrator role can connect, reconnect, disconnect, run Check again, or edit the legacy API key, and the account’s plan must include Apple Ads settings. The Apple Ads connection is stored per Qonversion project: connecting, checking or disconnecting acts on the currently selected project only. A read-only Apple Ads role still powers full reporting; only campaign management needs a write-capable Apple role.

​
Where do I connect Apple Ads?

The Apple Ads connection is managed in the Qonversion dashboard under Settings → Connections → Apple Ads (URL path /project-settings/asa). The page title is Apple Ads and its lead reads “Connect Apple Ads, verify access, and see exactly what Qonversion can do.” When you open the Apple Ads settings from the Apple Ads report, the page shows ← Back to Apple Ads, which returns you to the report with its filters.

​
Who can connect Apple Ads?

Only the Owner and Administrator roles can connect, reconnect, disconnect, run Check again, or edit the legacy API key for Apple Ads.
  • Members with other roles see the Apple Ads settings page read-only: buttons are disabled and the page says “Only an Owner or Admin can connect Apple Ads.”
  • If a user without permission tries to start the connection, the dashboard shows “You do not have permission to connect Apple Ads for this project.”
  • On the Apple Ads report, members who are not Owner or Administrator see connection problems with “Ask an account owner or administrator to reconnect it.” and no reconnect button; the report’s connect buttons are disabled for them and read Apple authorization unavailable.
  • For accounts that have the Apple Ads report, the Owner, Administrator, Manager, Analyst, Viewer and Observer roles can view it; viewing needs no extra permission beyond access to the project. The Developer role is the exception: it sees the Apple Ads item, but the report shows Apple Ads data is not available for your role instead of data.
  • The Manage Apple Ads campaigns capability does not include changing the Apple Ads connection (or importing spend history). A member who has it but is not an Owner or Administrator still cannot connect or disconnect Apple Ads. The capability covers campaign changes only — see How do I manage Apple Ads campaigns from Qonversion?.

​
Which plan do I need?

Connecting with Apple, running Check again for an Apple authorization, generating a key and saving legacy credentials all require a plan that includes Apple Ads settings. If your plan does not include Apple Ads settings:
  • The Apple Ads settings page shows the banner “Apple Ads is available only on the Growth plan.” with an Upgrade plan button.
  • The connect button is disabled and reads Apple authorization unavailable; the report’s Connect with Apple buttons read the same.
  • Editing or saving legacy credentials and the key wizard are unavailable.
  • An existing Apple authorization can still be disconnected; only the Owner or Administrator role is required for that.
  • The API answers 403 with “Apple Ads is not available on your plan.” or “Apple Search Ads is not available on your plan.”
  • If your account can see the Apple Ads report, the connection cannot be changed from the dashboard: when the connection needs attention (expired, rejected, unavailable or out of date), the report banner offers Contact support instead of a reconnect or review button.
The connect button also reads Apple authorization unavailable when Apple authorization is switched off for the project; the page then shows “Apple authorization is not available for this project right now. Your existing Apple Ads connection is unchanged.”

​
Which Apple Ads role does the Apple account need?

Apple Ads roles that allow campaign management from Qonversion on accounts with campaign management enabled: Role names are matched case-insensitively; any role not in the write-capable list is treated as read-only. A read-only Apple Ads role still powers full reporting — only campaign management is unavailable. Qonversion shows such an organization as Reporting only under Account access and shows Read-only in the Campaign management row. A write-capable Apple Ads role is necessary but not sufficient: campaign management must also be enabled for your account. On accounts with the Apple Ads report only, no changes are possible with any Apple Ads role — contact support.

​
How do I connect with Apple?

1

Open the Apple Ads connection

In the Qonversion dashboard, select the project and open Settings → Connections → Apple Ads. You need the Owner or Administrator role.
2

Select Connect with Apple

Select Connect with Apple. The button shows Opening Apple… while Qonversion hands you off to Apple.
3

Sign in and grant access on Apple's page

Sign in with Apple, choose the Apple Ads account and grant access. No private API key needs to be created or uploaded.
4

Return to Qonversion

After Apple sign-in you return to where you started: to Settings → Apple Ads when you started there, or to the Apple Ads report when you started from the report (including Settings opened from the report). On success the dashboard shows “Apple Ads connected. Access was verified with Apple.” If Apple access is still being checked, it shows “Apple authorization was saved. Qonversion is still checking account access.”
5

Check the connection status

The status can be Verifying right after authorization and becomes Connected only after Apple confirms access. Review Reporting access, Campaign management and Account access on the page.
The Apple authorization link is single-use and expires. Connecting with Apple on a project that has a legacy API key switches the project to Apple authorization; the legacy key fields are no longer shown or used. Connecting Apple Ads does not collect user-level attribution. Attribution collection is a separate step in your app with the Qonversion SDK — see How do I collect Apple Ads attribution with the Qonversion SDK?.

​
What errors can Connect with Apple show?

If the return from Apple fails before Qonversion can identify the connection attempt (authorization temporarily unavailable or an incomplete response from Apple), you land on the Apple Ads report with the error instead of the page where you started.

​
What does each connection status mean?

The Connection status card shows an overall status pill and three rows: Apple authorization, Reporting access and Campaign management. Reporting access and campaign management are reported separately. Once Apple has been checked, the card footer shows “Last checked with Apple:” followed by the date and time of the last check. When Apple’s permission check is too old, Reporting access shows Check out of date and Campaign management shows Refresh required (“A fresh Apple permission check is required before Qonversion can make changes.”). The Campaign management row shows: The Campaign management row and the per-organization pills reflect only the Apple Ads roles, not whether campaign management is enabled for your account: on an account with the Apple Ads report only they can show Available or Campaign management although no changes are possible.

​
How does Check again work?

Check again asks Apple to verify access again. Only an Owner or Administrator can run it.
  • For an Apple-authorization connection, Check again re-verifies access with Apple right away and shows “Apple verification status refreshed” on success.
  • For a legacy API-key connection, Check again (when the page offers it) asks Apple to verify the saved key and reports one of: verified N organization(s), Apple rejected this key, Apple Ads was unavailable, or no usable organizations. Each result states that the last saved connection is unchanged.
If Check again fails, the dashboard shows one of these messages:

​
How do I reconnect Apple Ads?

The main connection button changes with the project’s state: Reconnecting follows the same Apple sign-in flow as connecting. A reconnect is not available from the API or MCP — a person has to sign in with Apple in the dashboard.

​
How do I disconnect Apple Ads?

For an Apple-authorization connection:
1

Select Disconnect

On Settings → Connections → Apple Ads, select Disconnect. The confirmation “Disconnect Apple Ads?” reads “Disconnect Apple Ads from this project? Reports and campaign controls will stop until you reconnect.”
2

Confirm

Confirm with Disconnect Apple Ads.
A successful disconnect shows “Apple Ads disconnected”; a failed one shows “Could not disconnect Apple Ads”. Disconnecting stays possible after a plan downgrade; only the Owner or Administrator role is required. After you disconnect an Apple authorization, the overall status and Apple authorization row show Disconnected with “Apple Ads was disconnected from this project. Connect with Apple to resume.” Select Connect with Apple to restore the connection. Disconnecting acts on the currently selected Qonversion project only. To remove a legacy API-key connection, see How do I remove a legacy API key?.

​
Can I connect several Apple Ads organizations?

Yes. One Apple authorization can reach several Apple Ads organizations. Qonversion reads Apple’s access list and checks every organization the authorization can reach. Connecting several organizations is not a problem: reporting covers all of them; on accounts with campaign management enabled, campaign management is available in the organizations where your Apple role can write, and each change is checked against the organization that owns that campaign. Under Account access, each organization is listed with:
  • its name, or Apple Ads account <id>;
  • Org <id> · <currency> · <Apple roles> (currency and roles are omitted when unknown);
  • a pill: Campaign management (write-capable role), Reporting only (read-only role) or Checking access.
The Account access list is not shown while the authorization is being verified, or when the connection needs reconnecting, was rejected or is unavailable.

​
How do I use a legacy API key instead?

Apple authorization (Connect with Apple) is the recommended way to connect. The legacy API-key path is reached via Use a legacy API key instead, labelled “For rollback only. New connections should use Apple authorization above; customer .p8 keys will be removed after the migration window.” Only Owners and Administrators can open it. Saving legacy credentials and the key wizard require a plan that includes Apple Ads settings.

​
Generate a key without a terminal

While no legacy key is stored, the legacy path offers Connect without a terminal:
1

Let Qonversion generate the key pair

Qonversion generates the key pair. “The private key is created and stored on Qonversion servers — it never leaves them.”
2

Create the Apple API user and paste the public key

Create the Apple API user with a write-capable role — Admin or Campaign Manager, not “API Read Only” — so campaigns can be managed from the report later. Paste the public key into Apple Ads → Settings → API.
3

Enter the IDs Apple shows

Enter the Client ID, Team ID and Key ID Apple shows, then press Connect.
Generate a new key replaces the pending generated key. You must then paste the new public key into Apple Ads again; the previously pasted one is no longer used.

​
Enter an existing key

The legacy credentials are Client ID, Team ID, Key ID and Private key. All four are saved together with Save & check (“The four credentials are saved together — changes apply when you press Save & check.”). A saved private key is never shown or returned again; the dashboard only indicates Private key stored.
Saving a legacy API key on a project connected through Apple authorization replaces that authorization. Once the new key passes format checks (all four fields, ID lengths), Qonversion revokes the Apple authorization and switches the project to the key. The key itself is not checked with Apple before the switch.

​
How do I remove a legacy API key?

Clear all four credential fields (use Remove on the private key) and press Save & check. This deletes the project’s stored key and any pending generated key. It requires the Owner or Administrator role and a plan that includes Apple Ads settings; without the plan the fields are locked and the API answers 403 “Apple Search Ads is not available on your plan.” (unlike disconnecting an Apple authorization, which stays possible).

​
Which Apple Ads report does my account have?

The Apple Ads report is available on all accounts: a top-level Apple Ads item in the sidebar opens it (/apple-ads-report). An account without it keeps the older Apple Search Ads page under Analytics (/apple-search-ads). If your account still shows Apple Search Ads under Analytics and no top-level Apple Ads item, your account does not have the Apple Ads report; for such accounts the Apple Ads report endpoints answer 404 Not Found. Contact support. The same 404 also comes on an account with the report only (campaign management not enabled) for a project without per-app scope. Campaign changes and importing older spend history need campaign management to be enabled for your account — contact support. On accounts with the report only, the report is read-only.

​
Can I connect Apple Ads from the API or MCP?

No. The API and MCP cannot start or complete the Apple sign-in. To connect or reconnect, a person must use the dashboard link returned in dashboard_url (Settings → Apple Ads). Never paste a private key into a chat or send it to an agent. The API and MCP report the connection status only:
  • REST API: GET /v4/integrations/apple-ads/connection returns the project’s Apple Ads connection status with the fields state, connection_method, granted_at, last_verified_at, reporting, campaign_management, orgs[], next_action and dashboard_url. It is status-only and never returns keys or tokens. It answers 404 for accounts without access to the Apple Ads report.
  • MCP: the tool get_apple_ads_connection_status takes no parameters, needs the analytics:read scope, returns the same connection status, and never starts the Apple sign-in or returns credential material.
On an account with the Apple Ads report only, a project without per-app scope that already has a connection or spend reports reporting.state not_ready (app_scope_not_ready) whatever the state; its report data is not available. campaign_management.state is ready (can_write is true when any organization is writable), read_only (reason no_writable_org), not_ready (not_connected or authorization_revoked; campaign_management_not_enabled when campaign management is not enabled for the account), or unknown with reason permissions_not_checked_yet or permission_data_stale (can_write is null). unknown is not a refusal: do not tell the user they cannot change campaigns. next_action is connect_apple_ads, reconnect_apple_ads, wait_for_verification, migrate_to_apple_authorization, grant_campaign_role_in_apple_ads (all organizations are read-only; not used on accounts with the report only), wait_for_app_scope (report data for the project is not available yet; reconnecting does not help) or null. granted_at, last_verified_at and campaign_management.checked_at are RFC 3339 timestamps, null when never set. The response is not cached.

​
What is not supported?

  • Connecting or reconnecting Apple Ads through the REST API or MCP. A person must sign in with Apple in the dashboard.
  • Connecting, reconnecting, disconnecting, Check again or editing the legacy key by any role other than Owner or Administrator, including members who have the Manage Apple Ads campaigns capability.
  • Connecting with Apple, Check again for an Apple authorization, generating a key or saving legacy credentials on a plan without Apple Ads settings.
  • Campaign management from Qonversion with a read-only Apple Ads role (reporting still works).
  • Viewing a saved private key again.
  • Sharing one connection across projects: each Qonversion project has its own Apple Ads connection.