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
Bothdocker-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 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.
apps/api/.env: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:
apps/api/.env points at the same database:
Rotate the key
Generate and upload a new key as above, replace the file inapps/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.