Broctic

Connect App Store Connect

Generate a Team API key with Sales and Finance access, find your Issuer ID, Key ID and Vendor Number, and connect them to Broctic.

What you are connecting, and why

Broctic reads Apple's Sales and Trends reports through the App Store Connect API. To do that it needs four things from your Apple account: an Issuer ID, a Key ID, the .p8 private key those two identify, and your Vendor Number, which is the account the reports are filed under. The first three come from one page; the fourth deliberately does not, and that is the step people get stuck on.

The whole thing takes about five minutes and requires no code. When it is done, Broctic pulls the newest three weeks immediately and then backfills up to a year of daily history.

You need the right role in App Store Connect

Only an Account Holder or Admin can generate API keys. The key itself must be a Team key — individual keys cannot access Sales and Finance, whatever role their owner has.

Step by step

  1. 1. Open Users and Access → Integrations → Team Keys

    Sign in to App Store Connect and open Users and Access. Select the Integrations tab, then Team Keys in the sidebar.

    This is the part worth being pedantic about: the Integrations tab also offers individual keys, and a key generated there authenticates as a person. Sales and Finance reports are only available to Team keys, so an individual key produces a permission error later, at a point where it looks like the credentials are wrong rather than the key type.

  2. 2. Generate the key with Sales access

    Click Generate API Key (or the + button), name it something you will recognise in a year — Broctic is fine — and choose an access role.

    • Admin always works.
    • Finance or Sales is enough for sales reports and is the narrower grant, which is the better habit.
    • Anything without Sales or Finance access will authenticate fine and then fail to download a report — a 403, not a 401.

  3. 3. Copy the Issuer ID

    After the key is generated, the Issuer ID appears above the keys table. It is a UUID and it is shared by every key in the account, so if you have connected another tool with an App Store Connect key, it is the same Issuer ID.

  4. 4. Copy the Key ID

    The Key ID is in the row of the key you just created — a short alphanumeric string of about ten characters. It identifies which key a request is signed with, so it must match the .p8 file you download next.

  5. 5. Download the .p8 — you get one chance

    Click Download API Key in the key's row. The file is named something like AuthKey_ABC1234DEF.p8.

    Apple allows this download exactly once

    There is no way to download it again and no way to recover it from Apple. Keep it in your password manager. If it is lost, revoke the key in App Store Connect and generate a new one — nothing already ingested is affected.

  6. 6. Find the Vendor Number (a different page)

    The Vendor Number is not on the Integrations page, and Apple's API does not expose it, which is why Broctic has to ask you for it rather than discovering it.

    In App Store Connect, open Payments and Financial Reports. The vendor number is shown at the top of the page, in the form Vendor #87654321. Copy the digits only — no #, no spaces.

    It identifies the account the sales reports are filed under. A wrong vendor number does not fail authentication; it succeeds and returns nothing, which reads exactly like an app with no sales.

  7. 7. Paste all four into Broctic

    Sign in to Broctic and go to Settings → Integrations → App Store Connect. Enter the Issuer ID, the Key ID and the Vendor Number, then paste the entire contents of the .p8 file — including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines. Line breaks mangled by copying through a terminal or a chat window are repaired automatically.

    Broctic calls Apple with the key before storing it. If Apple rejects it you get the error immediately and nothing is saved. If it works, the key is sealed with AES-256-GCM and the apps it can see are listed straight away.

What happens next

  • The apps your key can see are listed immediately, so you can link each one to an app in Broctic (or import it as a new one).
  • The first sync pulls the newest 21 days, so this week is on the page in the first minute rather than after a backfill.
  • History fills in over the following hours, up to Apple's one-year limit.
  • After that, a scheduled job syncs hourly — whether or not anyone has the console open.
  • Apple publishes each day's sales report by 08:00 Pacific the next morning. Yesterday is the newest day that can exist; nothing here is real time, and the console says how fresh it is rather than implying it is live.

Selling in the app needs a second key

This key reads reports and manages the listing. Purchases — whether a person is entitled, and revenue per onboarding arm — use Apple's separate In-App Purchase key, under Users and Access → Integrations → In-App Purchase. See purchases.

Troubleshooting

  • 400 from Apple — the Issuer ID, Key ID and .p8 do not agree. The usual cause is a Key ID from one key and a .p8 from another. Re-copy both from the same row.
  • 403 from Apple — the key authenticated but is not allowed to read sales. Either it is an individual key rather than a Team key, or its role has no Sales or Finance access. Generate a Team key with Admin, Finance or Sales.
  • 401, or "invalid token" — the .p8 contents are incomplete. Paste the whole file, BEGIN and END lines included.
  • Connected, but no reports ever arrive — almost always a wrong Vendor Number. It is the one field a bad value fails silently on: Apple answers, politely, that this vendor has no reports. Re-check it under Payments and Financial Reports.
  • An app shows nothing while others work — Apple returns a 404 for an app that has never been published, and Broctic records that as "done, nothing to fetch" rather than an error.
  • Yesterday is missing before 08:00 Pacific — that is Apple, not Broctic. The console says "not published yet" before the deadline and "Apple reported no sales" after it, because those are different facts.

Security

The key can read your company's revenue, so it is treated the way that deserves: verified against Apple before storage, encrypted at rest with AES-256-GCM, decrypted only by the code path that signs a request to Apple, and returned by no API route. Disconnecting deletes it.

Read the privacy policy for what is stored and for how long.

Frequently asked

Why does Broctic need a Team key rather than an individual key?
Apple only exposes Sales and Finance reports to keys generated under Users and Access → Integrations → Team Keys. An individual key authenticates as one person and cannot download sales reports at all, so the connection fails with a 403 no matter what role that person holds.
Where is the Vendor Number in App Store Connect?
Under Payments and Financial Reports, shown at the top of the page as Vendor #87654321. It is not on the API keys page and Apple's API does not return it, which is why Broctic has to ask for it. Enter the digits only, without the # sign.
Can Broctic see my private key after I paste it?
No. The key is verified against Apple before it is stored, sealed with AES-256-GCM, and no API route returns it. Only the code path that signs a request to Apple can decrypt it.
How far back does the data go, and how often does it refresh?
The first sync pulls the most recent 21 days so you see this week immediately, then history fills in over the following hours up to Apple's one-year limit. After that a scheduled job syncs hourly. Apple publishes each day's report by 08:00 Pacific the next morning, so yesterday is the newest day that can exist.
What if I revoke the key later?
Revoking the key in App Store Connect stops the sync; Broctic marks the connection invalid and says so instead of showing stale figures as current. Sales already ingested stay in your account.