Proceeds
App Store Connect API keys: which key and role can read your sales data
You make an App Store Connect API key, paste it into a dashboard, and nothing shows up. No crash, no obvious error, just an empty screen. Almost always the key itself is fine. The problem is the kind of key you made, or the role attached to it.
Apple documents the rules, but across three pages that do not link to each other: the key-creation page, the account role grid, and the role note buried in the Analytics API collection. This page puts them side by side, with every rule read off Apple's own documentation and linked at the bottom.
Sales and finance endpoints require a Team key, and the key only works if its role can read reports: Account Holder, Admin, Finance or Sales for sales and trends, and Account Holder, Admin or Finance for payments and financial reports.
There are two key types, not three
Apple's key-creation page documents two kinds of App Store Connect API key. A Team key has, in Apple's words, access to all apps, with varying levels of access based on selected roles. An Individual key has the access and roles of the user it belongs to.
The difference matters immediately, because Apple states that Individual keys cannot use provisioning endpoints, cannot access Sales and Finance, and cannot use notarytool. The Sales and Finance collection repeats it from the other side: those endpoints require a Team key and are not usable with an Individual key. If you generated your key from your own user profile, that is an Individual key, and no amount of fiddling will make it return revenue.
There is no Marketing key type and no Analytics key type. Marketing is an account role, not a key type. People say otherwise, but Apple's documentation lists two types and only two.
Making a Team key needs an Admin account in App Store Connect. If you are the only person on your team, you already have one. If someone else owns the account, they have to make the key for you, or grant you the Generate Individual API Keys permission, which gets you a key that still cannot read sales.
| Team key | Individual key | |
|---|---|---|
| Who can create it | An Admin account | Any user with the Generate Individual API Keys permission |
| App scope | All apps on the team | The apps the user can access |
| Sales and finance endpoints | Yes, subject to role | No, Apple excludes them |
| Provisioning endpoints | Yes, subject to role | No |
| notarytool | Yes | No |
| JWT payload | Uses the issuer ID in iss | Uses sub set to user, no iss |
The role on the key decides which reports come back
Apple says the roles that apply to keys are the same roles that apply to users on your team. So the question of what your key can read is the question of what that role can read, and Apple publishes a grid for it on its program roles page.
The grid is a set of checkmark images, which is why third-party role tables on the web disagree with each other. Here is what the cells actually say. Four roles get reporting access at all. The other four, App Manager, Developer, Marketing and Customer Support, get none of it.
One cell is not a plain yes. On the Sales row, the right to view sales and trends reports carries the note that it requires access to reports, granted separately in Users and Access. A Sales key can therefore see the Sales and Trends dashboard and still fail to download the report files, which is a confusing way to be half-configured.
| Role | App analytics | Sales and trends | Sales and trends reports | Payments and financial reports |
|---|---|---|---|---|
| Account Holder | Yes | Yes | Yes | Yes |
| Admin | Yes | Yes | Yes | Yes |
| Finance | Yes | Yes | Yes | Yes |
| Sales | Yes | Yes | Requires reports access | No |
| App Manager | No | No | No | No |
| Developer | No | No | No | No |
| Marketing | No | No | No | No |
| Customer Support | No | No | No | No |
Analytics reports follow a second, different rule
The Analytics Reports API is not the same thing as Sales and Trends, and it has its own role rule written on its own page. Apple says that to download analytics reports you need one of three roles: Admin, Sales and Reports, or Finance.
Within those three, the permissions split. Only Admin can create a report request or delete one. Finance and Sales and Reports can list and download the reports that already exist, and nothing more. So a Finance key can read analytics data that somebody else set up, but cannot start a new ongoing report.
A naming wrinkle worth knowing before you go looking for it: Apple's account role grid calls the role Sales, while the Analytics API page calls it SALES AND REPORTS. Apple does not publish anything reconciling the two names, so treat them as the same role under two labels and check the actual permissions in Users and Access rather than trusting the label.
Analytics data is also deliberately imprecise in places. Apple says it adds noise to some reports, applies crowd anonymity to others, uses both on some, and only reports totals once a certain number of data points exist. A gap in an analytics report is not always a bug in whatever is reading it.
What an empty response usually means
Work down this list before suspecting the tool you pasted the key into. Each item is a thing Apple's documentation says will block the data, except the last two, which are labelled.
- The key is an Individual key. Sales and finance endpoints reject it by design.
- The role has no reporting access. Marketing, Developer, App Manager and Customer Support keys get nothing from these endpoints.
- The role is Sales and nobody granted reports access in Users and Access, so dashboard access works but report downloads do not.
- You asked for payments and financial reports with a Sales key. That row is Account Holder, Admin and Finance only.
- The JWT expired. Apple rejects tokens that expire more than 20 minutes into the future, so a long-lived token is not an option.
- The filter combination is invalid. Apple lists exactly which reportType, reportSubType, frequency and version values go together, and says other combinations produce an error.
- You requested a deprecated report. Apple stopped generating new INSTALLS reports as of November 4 2026, with no replacement report type, though historical ones still download.
- Developer-reported, not documented by Apple: some tools surface a role-blocked report as an empty result rather than an error, because the request technically succeeds. Apple documents a 401 Request not authorized response on the report endpoints, so behaviour varies by client.
You get one chance to download the private key
When you create a key, App Store Connect offers the private key for download exactly once. Apple's wording is blunt: the download link only appears if you have not downloaded the private key, and Apple does not keep a copy. Lose it and the only path forward is a new key.
Two other values travel with it. The key ID and the issuer ID both live under Users and Access, on the Integrations tab, and you can copy them any time. Only the private key is the one-shot download.
Store the private key the way you would store any other secret. On iPhone, the Keychain is the normal place for it. Proceeds, per its App Store listing, keeps the key in the device Keychain and reads App Store Connect directly rather than relaying your figures through a server.
If a key is ever exposed, revoke it rather than rotating around it. Apple says revocation is immediate and permanent, that you cannot reinstate a revoked key, and that revoked keys stay visible on the API Keys page under a Revoked heading for 30 days. An Admin revokes team keys from Users and Access, on the Keys tab, and any user can revoke their own individual key from their profile.
Rate limits, and what Apple will and will not tell you
Apple limits how many requests you can send with a given API key, and applies the limit per key. Every response carries an `X-Rate-Limit` header in the form `user-hour-lim:3500;user-hour-rem:500;`, where the first number is your hourly ceiling and the second is what is left.
The window is a rolling hour, so the remaining count is your per-hour limit minus everything you sent in the previous 60 minutes. Go over and the API returns HTTP 429 with the error code `RATE_LIMIT_EXCEEDED`.
Apple does not publish the actual number. The 3500 in its own documentation is an example inside a sample header, and the page says plainly that actual limits can vary. Figures circulating on forums and in blog posts, including 3600 per hour and a per-minute throttle, are developer reports rather than documented limits. Read the header if you want your own number.
Apple's advice for anything that polls on a schedule is to throttle requests to stay under the per-hour limit for the endpoint, and to handle the 429 by logging it and queuing the job for later rather than retrying hard.
What any app holding your key can and cannot do
This part is worth being exact about, because a dashboard is asking you to hand over a credential. Any client using your key has precisely the access the key has, no more and no less. There is no special partner tier, no privileged feed, and no way for an app to read a report your role cannot read. Proceeds is in the same position as any other client, including a script you write yourself.
What that access amounts to, with a Team key and a reporting role, is downloading report files. Sales and trends reports come from one endpoint with filters for frequency, report date, report type, report sub type, version and your vendor number. Financial reports come from another, keyed on a region code, the report type FINANCIAL, your vendor number, and a report date that is a fiscal month in YYYY-MM format rather than a calendar one.
The flip side is that a key you give out is a key that can do everything its role allows, not just read numbers. An Admin key can create and delete users. If you only want a tool to read revenue, give it the narrowest role that works, and consider the optional scope claim Apple supports in the JWT, which limits a token to specific request paths and makes a leaked token much less useful.
Questions
Why does my App Store Connect API key return no sales data?
The two common causes are the key type and the role. Apple's documentation says sales and finance endpoints require a Team key and are not usable with an Individual key, so a key generated from your own user profile will never return revenue. If it is a Team key, check the role: Marketing, Developer, App Manager and Customer Support have no reporting access at all in Apple's role grid.
Which role should I use for a read-only revenue dashboard?
Finance is the narrowest role in Apple's grid that covers both sales and trends reports and payments and financial reports. Sales covers sales and trends but not payments and financial reports, and on the Sales row Apple notes that report access has to be granted separately in Users and Access. Admin works too but can also create and delete users, which is more power than a dashboard needs.
Is there a Marketing API key?
No. Apple's key-creation page documents two key types, Team and Individual. Marketing is an account role rather than a key type, and in Apple's role grid it has no access to app analytics, sales and trends, sales and trends reports, or payments and financial reports.
I lost the private key file. Can I download it again?
No. Apple says the download link only appears if you have not already downloaded the private key, and that Apple does not keep a copy. Create a new key and revoke the old one. The key ID and issuer ID are different, and you can copy both at any time from Users and Access on the Integrations tab.
What happens when I hit the App Store Connect API rate limit?
Apple returns HTTP 429 with the error code RATE_LIMIT_EXCEEDED. Every response includes an X-Rate-Limit header showing your hourly limit and how many requests remain, measured over a rolling 60 minutes. Apple does not publish a fixed number and says actual limits can vary, so read the header rather than trusting a figure from a forum.
Does Proceeds get access to numbers I cannot see myself?
No. It uses the key you create, so it has exactly the access that key's role has. Per its App Store listing, the key stays in your device Keychain. Any report your role cannot download, no client can download on your behalf, and that includes Proceeds.
Every rule here is read from Apple's own documentation. Key types, the Individual key exclusions and the one-time private key download: developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api. The Team key requirement for revenue data: developer.apple.com/documentation/appstoreconnectapi/sales-and-finance. Report filters and the INSTALLS deprecation: the GET /v1/salesReports and GET /v1/financeReports reference pages. Analytics roles and privacy measures: developer.apple.com/documentation/appstoreconnectapi/analytics. The 20-minute token expiry and the scope claim: developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests. Rate limits: developer.apple.com/documentation/appstoreconnectapi/identifying-rate-limits. Revocation: developer.apple.com/documentation/appstoreconnectapi/revoking-api-keys. The role grid: developer.apple.com/support/roles/. Not verified: Apple does not name the private key file extension on its key-creation page, so none is stated here. Apple's role grid calls the role Sales while its Analytics API page calls it Sales and Reports, and no Apple page reconciles the two names. No actual rate-limit number is documented; the 3500 on Apple's page is an example. Whether a role-blocked request returns an empty result or a 401 varies by client and is developer-reported rather than documented. Descriptions of Proceeds are from its App Store listing.