Skip to main content
Without a key, App Store popularity is an estimate from public store signals. With one, AsoBeast reads Apple’s weekly search popularity for the terms Apple publishes and uses it instead. See Popularity, difficulty and opportunity for what changes in the scores. The key belongs to the instance, not to a workspace, and the data it reads is the same for every workspace on it.

Create the key

1

Generate a private key

Apple Ads accepts an elliptic curve key on the prime256v1 curve.
2

Upload the public key

In Apple Ads, open Account Settings, then API, and paste the contents of apple-ads-public.pem. Apple shows a client id, a team id and a key id. Keep all three.
3

Keep the private key out of the repository

Move apple-ads-private.pem into apps/api/keys/ beside your Compose files. Git ignores that directory, so the key is never committed.

Give the API the key

Both docker-compose.yml and docker-compose.pull.yml mount apps/api/keys read only into the API container, at the path the API resolves a relative key path against. Nothing else needs mounting, whether you start the stack with docker compose directly or through pnpm compose:build:prod.
1

Let the API read the key

Inside the container the API runs as user id 1000. On a Linux host, give that user the file:
Docker Desktop on macOS and Windows maps file ownership itself, so there the file only has to be readable by you.
2

Set the four variables

In apps/api/.env:
Set all four or none. A partial set refuses to boot and names the missing ones, and so does a key file the API cannot read, which names the path it tried. APPLE_ADS_AD_ACCOUNT_ID is optional; see the configuration reference.The relative path works unchanged for pnpm dev, which runs the API from apps/api.
3

Recreate the API

Confirm the sync ran

The sync runs every Monday at 09:00 UTC by default, after Apple posts the week that ended on Saturday. To run it now, sign in as the platform operator, open /admin/queues, select the pipeline queue and promote the apple-popularity repeatable job. Then count what was stored per market and week:
A keyword Apple lists shows the source “Apple Ads search popularity” and high confidence once it is next scored. Score one from its row actions to see it at once. To see how the estimate compares with Apple’s number on your own keywords, run the calibration command from a source checkout whose apps/api/.env points at the same database:
Below ten keywords with both numbers it says there is not enough data yet.

Rotate the key

Generate and upload a new key as above, replace the file in apps/api/keys/ and APPLE_ADS_KEY_ID, recreate the API, then revoke the old key in Apple Ads. Stored popularity stays valid, because it is Apple’s published data rather than anything tied to the key.

Disconnect

Remove the four variables and recreate the API. The weekly sync is unscheduled on the next start and scoring returns to the estimate. Stored weeks stay in the table but are no longer read.
Last modified on November 20, 2026