Before you start

For public rankings, search for an app by name or paste its App Store link. No key is needed. For connected reports, you'll need:

  • Perch on a Mac running macOS 14 or later or an iPhone running iOS 17 or later.
  • An App Store Connect team API key. The Account Holder or an Admin can create one after API access is approved.
  • Your Key ID, Issuer ID, Vendor Number and downloaded .p8 file.

I'll guide you through. Apple's UI gets a bit cluttered, but we'll find each piece together.

01

Generate an App Store Connect API key

Sign in to App Store Connect and follow the path above. If API access has not been approved, the Account Holder must request it first. Choose Team Keys.

Diagram of the App Store Connect Users and Access page with the App Store Connect API sidebar item highlighted and the Generate API Key button called out.
Choose Generate API Key or the add button and name it Perch. Select permissions for the features you plan to use. Sales access should not be treated as sufficient for review replies. Apple lists Account Holder, Admin or Customer Support for replying to reviews. Check Apple's role permissions and review-reply guidance with your team. This guide does not promise that a single role enables every Perch feature.

Apple creates the key and gives you three things you'll need:

  • Issuer ID UUID at the top of the page, above the keys list.
  • Key ID Ten characters, shown in the new key's row.
  • .p8 file Choose Download API Key. Apple only allows one download, so store the file securely.
02

Find your Vendor Number

In App Store Connect, open Payments and Financial Reports and select Reports. Copy the Vendor Number shown under your legal entity name.

Diagram of Payments and Financial Reports with an example Vendor Number called out.
Use the Vendor Number for the team whose reports you want to read. The number in this diagram is an example.
03

Paste it all into Perch

On Mac, open Perch from the menu bar, open Settings and expand Credentials. On iPhone, open Settings and tap the connection card to add or edit your key.

Illustration of the key details used by Perch, with example identifiers and a key file.
Enter the three identifiers and choose the .p8 file you downloaded. The controls look different on Mac and iPhone.
  • Key IDPaste from step 1.
  • Issuer IDPaste from step 1.
  • Vendor NumberPaste from step 2.
  • .p8 fileChoose the downloaded .p8 file using the key-file control.

Choose Save credentials on Mac or Connect my apps on iPhone. Perch tests the key with Apple and saves it in the Keychain. It also saves a copy for iCloud Keychain sync.

04

First sync

Perch fetches app details, available sales reports, recent reviews and app status. The first sales sync can work back through up to 365 days of reports. The time needed depends on your connection, available reports and key permissions.

Later syncs check for updated reports, reviews and app status. Your Mac refresh interval and iPhone background scheduling affect when these checks run. Public chart checks run separately.

Perch 2.0 on Mac with sample installs, revenue, reviews and rankings after syncing.
Perch 2.0 on Mac. Illustrative sample data.

Something went wrong?

If Perch cannot connect, check these details:

  • Issuer ID or Key ID typed wrong. They're long. Easy to drop a character.
  • Wrong .p8 file. If you have several, double-check you picked the one matching this Key ID.
  • Vendor Number missing or incorrect. Sales reports need the right number for your team.
  • Key revoked or permissions missing. Check that the key is active and has access to the data or review action you need. Revoking a key stops new connected requests from being authorised. It does not remove public ranking access.

If you're stuck, send a note. Plain English description of what's happening, and we'll write back.

Privacy, in case you're wondering

Perch keeps credentials in the system Keychain on Mac and iPhone. A separate copy can sync through iCloud Keychain with end-to-end encryption. Reports can sync through your private iCloud database. Watched-app IDs, currency settings, cached rates and rank-alert records use iCloud key-value storage. There is no Perch account or Perch server. Feedback you send includes automatically attached setup details.

More on the privacy page.