The App Store Connect API key, explained
The credential every iOS automation runs on: how to create one, which role to give it, why the .p8 downloads exactly once, and the one thing it still cannot do.
· 7 min read
Every iOS automation that is not a person clicking in a browser runs on one credential: an App Store Connect API key. Fastlane uses it. Codemagic uses it. NoMac uses it. It is worth ten minutes of understanding, because the failure modes are all quiet ones — a key with the wrong role fails at the last step of your first release, not the first.
What it actually is
A key is three values, and you need all three:
- ·Issuer ID — one UUID for your whole team. Same for every key.
- ·Key ID — ten characters identifying this key.
- ·The private key — a
.p8file, downloadable exactly once.
Tools sign a short-lived JSON Web Token with the private key and send it as a bearer token. Those tokens are valid for at most twenty minutes, which is why every library regenerates them per run and why a clock skewed by more than a few minutes produces authentication errors that look like permission errors.
The .p8 downloads once. Apple shows the download button after you generate the key and never again. Lose it and the only path is revoke and regenerate. Put it in a password manager or a secret store the moment it lands in your downloads folder — not in the repository, where it becomes a credential in your git history forever.
Creating one
- ·App Store Connect → Users and Access → Integrations → App Store Connect API.
- ·Only the Account Holder, or an Admin the Account Holder has granted access, can create keys. If the button is missing, that is why.
- ·Name it after the thing that will use it — “CI” tells you nothing in a year.
- ·Pick the role. App Manager is the right default for shipping: it can manage apps, builds and TestFlight, but not your team.
- ·Generate, then download the .p8 immediately.
Which role to pick
Developer is enough to upload builds and manage TestFlight, and not enough to create the App Store version or submit for review. Teams that pick it for least-privilege reasons discover the gap at submission time.
App Manager covers the whole shipping loop — builds, TestFlight, metadata, submission — without granting user management. This is the one to use.
Admin is broader than any pipeline needs. Reserve it for a human.
What the key can do
- ·Create and renew signing certificates and provisioning profiles.
- ·Upload builds, without an Apple ID password and without 2FA prompts.
- ·Manage TestFlight groups, testers and build distribution.
- ·Read tester feedback and crash reports back out.
- ·Write app metadata, upload screenshots, and create a review submission.
That covers everything that happens repeatedly. Which is the point: the recurring path needs no human, no password, and no session that expires at an inconvenient moment.
What it cannot do
It cannot create the app record.The first existence of an app in App Store Connect — bundle ID, name, primary language — is a one-time manual step. No key gets around it, and any tool that claims a fully automated path from zero either has you doing that step yourself or is submitting under someone else's account, which is its own rejection risk.
It also cannot answer the questions only you can answer: the App Privacy label, the age-rating questionnaire, export compliance declarations. Those are attestations, not data entry — see Apple's three paperwork blockers.
Why not just use an Apple ID?
Because it breaks. Session-based Apple ID authentication is unofficial, needs 2FA, and the session expires on Apple's schedule — typically monthly, always at the worst time. It cannot run unattended, which makes it unusable for an agent. Tools built on it accumulate a troubleshooting cottage industry around re-authentication. The API key exists precisely so automation does not have to impersonate a person.
NoMac asks for a key rather than your Apple ID for exactly this reason, and it stays yours: revoke it in App Store Connect and our access ends that second, with no support ticket.
Rotating and revoking
- ·Revoke immediately if a .p8 is ever committed, pasted into a chat, or emailed.
- ·Rotate on team changes — a key outlives the person who made it.
- ·One key per system, so revoking one thing does not break three.
# what a tool needs from you ASC_ISSUER_ID=69a6de70-... # team-wide UUID ASC_KEY_ID=ABCD123456 # this key ASC_PRIVATE_KEY=AuthKey_ABCD123456.p8 # downloaded once
With those three in place, the rest of the pipeline is mechanical. If you would rather not wire it up yourself, npx @nomac/cli login and the setup wizard walks the same path with live validation at each step — see the CLI reference.