The App Store Connect API is a REST API you authenticate with a token you sign yourself.

How the token is built, and how long it lives

Authentication is ES256 the whole way down. Apple states that all JWTs for the App Store Connect API must be signed with ES256, using the private key that matches the key ID you name in the header. The header itself carries three fields and nothing else: alg set to ES256, kid set to your private key ID, and typ set to JWT.

The payload depends on which kind of key signed it. A team key uses iss, the issuer ID from the API Keys page, together with iat, exp and aud set to appstoreconnect-v1. An individual key does not use iss at all. Apple documents that individual keys instead require the sub key, and that its value is always user. An optional scope claim narrows the token to a list of operations, written out as method and path, for example GET /v1/apps with a platform filter.

Lifetime is where most first attempts fail. App Store Connect works out the lifetime of a token by subtracting the iat claim from the exp claim, and Apple documents that for most requests it rejects a token with a lifetime greater than 20 minutes. There is one documented exception: a token whose scope contains only GET requests, on resources that allow long lived tokens, may have a lifetime of up to six months. Apple also advises picking the shortest lifetime that does the job, and offers two minutes as an appropriate lifetime for a one off request.

Once signed, the token travels in an Authorization header as a bearer token, on every single call. There is no session, no refresh token and no cookie to keep warm. Because iat and exp are absolute Unix times, a machine with a badly wrong clock will happily mint tokens that were never inside the window.

Apple, generating tokens for API requests

The key carries a role, and the role is the blast radius

You create an App Store Connect API key in App Store Connect under Users and Access, in the Integrations tab. Apple documents two kinds. A team key gives access to all apps, with varying levels of access based on the selected roles, and you need an Admin account to generate one. An individual key carries the access and roles of the user it belongs to, and Apple says plainly that individual keys are not able to use Provisioning endpoints, access Sales and Finance, or use notaryTool. If your script touches certificates or profiles, that sentence decides which key you need.

The role is not paperwork. Apple documents that when you create a key you assign it a role that determines the key access to areas of the API and its permissions for performing tasks, and that the roles which apply to keys are the same roles that apply to users on your team. A key with the Admin role has broad permissions and can do things like create new users and delete users. A nightly job that adds a tester to a beta group has no business holding that.

Then the detail that catches teams out: the private key is available for download a single time. The download link only appears while you have not yet downloaded it, and Apple keeps no copy. Secure it the way you would a password, and if you think it has leaked, revoke the key in App Store Connect straight away. Three values together are the whole credential: the issuer ID, the key ID, and the .p8 file itself.

Apple, creating API keys to authorize API requests

What the REST API reaches, and where it stops

The App Store Connect REST API is laid out much like the website. App Store covers apps, App Clips, in-app purchases and customer reviews. TestFlight covers prerelease versions, beta testers and beta groups. Provisioning covers bundle IDs, capabilities, certificates, devices and profiles. Reporting covers sales, finance and analytics. There is also Game Center, Xcode Cloud, webhooks, users and access, and alternative distribution. Responses come back as JSON carrying links to related resources, so you follow relationships instead of guessing at URLs.

TestFlight is the usual reason people start. Creating a beta group, adding testers, attaching a build and editing what those testers see are all ordinary calls, and the ios testflight guide covers what that same flow looks like from the store side rather than from a script.

Where it stops is the binary. Apple does not document an endpoint that accepts an .ipa. The upload operations in the API are for assets: screenshots, app previews, App Review attachments, routing coverage files. The build itself goes up through Xcode or Apple's Transporter app, and only once it has arrived does a build record exist for your code to act on. Plan the automation around that boundary and it stays simple.

Rate limits are per key and reported in an X-Rate-Limit response header, which names the hourly limit and how much of it is left, counted over a rolling hour. Go past it and you get a 429 with the error code RATE_LIMIT_EXCEEDED. Apple notes that actual limits can vary, so read the header rather than hard coding a number you saw in a blog post. If writing the HTTP client yourself is not the point, the app store connect cli route wraps most of this already.

What breaks when nobody is watching

Code that works on a laptop fails in CI for a short list of reasons, and they are nearly all about the key. The .p8 belongs in the secret store, never in the repository, and most CI systems want it base64 encoded to survive life as an environment variable. Write it to a temporary file at the start of the job, read it, delete it at the end, and never log it.

Mint the token inside the job, not before it. A twenty minute ceiling means a token created by an earlier step, or cached between runs, can expire in the middle of a long wait for processing to finish. Generate it at the point of use and generate a fresh one on retry. Then treat the failures as three different problems: a 401 is usually the token, a 403 is usually the role, and a 429 is the rate limit telling you to slow down.

It is also worth deciding early what this automation is for. Moving metadata, testers and release state is what the API does well. Producing the build that gets uploaded is a separate pipeline with its own signing and its own failure modes, and folding both into one script is how a team ends up with a job nobody can debug at release time.