How to create an App Store Connect API key: team or individual, the right role, and a .p8 you only get once

An App Store Connect API key is a key pair. Apple keeps the public half; you download the private half as a .p8 file and use it to sign the short-lived tokens that every API request carries. Here is everything a tool will ask you for, and where it lives.

What does a tool need from you?

The .p8 file is a PEM text file that begins with -----BEGIN PRIVATE KEY-----. If a tool complains that your key is the wrong format and the file says BEGIN EC PRIVATE KEY, you probably have a key made with OpenSSL rather than one downloaded from App Store Connect.

Team key or individual key?

Apple offers two kinds. The difference matters more than the setup steps.

Sources: Apple’s Creating API Keys for App Store Connect API and the App Store Connect API help page.

Use a team key for anything that works for the whole account: CI, a metadata tool, a sales dashboard. Use an individual key when a script should only ever see what one person sees. Since individual keys can’t read Sales and Finance, they’re no use for revenue tools at all.

How do you create a team key, step by step?

1. Request access, once. The Account Holder goes to Users and Access > Integrations, clicks Request Access, agrees to the terms and submits. Apple says requests are reviewed case by case.
2. Open Team Keys. In Users and Access > Integrations, with App Store Connect API selected in the left column, choose the Team Keys tab.
3. Generate. Click Generate API Key, or the + button if you already have an active key.
4. Name it. The name is only for you. Name it after the tool or the machine that will use it, so you know what breaks when you revoke it later.
5. Pick the role. Under Access, choose the role. Apple says you can’t edit a key’s name or access level afterwards; to change either, you revoke the key and make a new one.
6. Click Generate, then Download API Key next to the new key. Save the .p8 before you leave the page.
7. Copy the Issuer ID and Key ID into the tool, along with the file.

An individual key is shorter: click your name at the top right, Edit Profile, then Generate Key under Individual API Key, and Download.

Which role should the key have?

The roles for keys are the same ones you give people on your team. The rows below are from Apple’s role permissions table, narrowed to what API tools usually do:

Pick the smallest role that covers the job. A screenshot or metadata tool fits App Manager. A revenue dashboard fits Sales or Finance. A tool that edits metadata, replies to reviews and reads sales needs Admin, and Apple’s docs single that role out: an Admin key can create and delete users. Keep that file somewhere better than your Downloads folder.

Where should the .p8 file live?

Apple’s guidance is short. Treat the private key like a password; don’t share it, store it in a code repository or ship it in client-side code; and revoke it at once if it’s lost or exposed. Apple keeps no copy, so the file you downloaded is the only one.

In practice that means a password manager, the macOS Keychain, or your CI provider’s secret store, and then deleting the stray copy in Downloads. One key per tool helps too. Apple lets you generate multiple team keys, and if each tool has its own, revoking one doesn’t take the others down with it.

How do you revoke a key?

Revoking is immediate and permanent. Apple’s Revoking API Keys page says a revoked key can’t be reinstated; revoked keys stay listed for 30 days under Revoked.

• For a team key, an Account Holder or Admin opens Users and Access > Integrations > App Store Connect API, chooses Team Keys, clicks Edit, selects the key, clicks Revoke Key and confirms.
• For someone else’s individual key, it’s the same place under the Individual Keys tab, again as an Account Holder or Admin.
• For your own individual key, open Edit Profile, find Individual API Key and click Revoke.

Revoke a key when a laptop holding the file is lost, when someone who had a copy leaves, and when you retire the tool that used it.

What is a JWT, in one paragraph?

The API never sees your .p8 file. Each request carries a JSON Web Token (RFC 7519) that the tool builds and signs on your machine: a header saying it’s signed with ES256 and naming your Key ID (kid), and a payload with your Issuer ID (iss), the time it was issued (iat), its expiry (exp) and the audience appstoreconnect-v1, optionally narrowed with a scope list of allowed requests. Apple checks the signature against the public half it kept, so a valid signature proves the request came from whoever holds the private key. Tokens with a lifetime over 20 minutes are rejected for most requests, and Apple suggests reusing one token across requests until it expires (Generating Tokens for API Requests).

Header:  { "alg": "ES256", "kid": "2X9R4HXF34", "typ": "JWT" }
Payload: { "iss": "57246542-96fe-1a63-e053-0824d011072a",
           "iat": 1528407600, "exp": 1528408800,
           "aud": "appstoreconnect-v1" }

Those are Apple’s own example values: an exp 1,200 seconds after iat is exactly the 20-minute ceiling.

What do the common errors mean?

A token App Store Connect won’t accept usually comes back as 401 with the code NOT_AUTHORIZED. The usual causes are an Issuer ID and Key ID that don’t belong together, a token signed with a different key than the one its kid names, a lifetime over 20 minutes, or a computer clock that’s off. Apple’s status code table lists 403 Forbidden for a revoked key, a badly formatted token, or an operation the key isn’t allowed to do. If the token works for some requests and not others, it’s the role. 429 means you’ve hit the rate limit for that key.

How AppMeta uses your key

AppMeta, the Mac client for App Store Connect I wrote about in February, takes a team key: it asks for the Issuer ID, the Key ID and the .p8 file, so individual keys, which have no Issuer ID, don’t fit it. Before it saves anything it signs a token and asks App Store Connect for your app list, so a mismatched ID or a revoked key shows up as an error on the setup screen rather than later.

The three values go into the macOS Keychain as items that stay on that Mac and don’t sync through iCloud. AppMeta signs 20-minute ES256 tokens locally and reuses each one until it’s about two minutes from expiring, and the only server it sends them to is api.appstoreconnect.apple.com. Removing the account in AppMeta deletes the Keychain items.

For the role: App Manager covers editing metadata in every localization, the keyword field included, plus creating and submitting versions. Replying to reviews and the sales views need a role that allows them, and for a single key that means Admin. If you’d rather keep revenue on a separate key, the AppMeta Pulse API access page lists the endpoints Pulse calls and the role it asks for.