Login failures, two-factor prompts, and session expiry break Fastlane automation. Switch to an App Store Connect API key to fix authentication for good.
Fastlane talks to App Store Connect and the Apple Developer portal to upload builds, manage signing, and push metadata. Authenticating with an Apple ID and password is fragile because Apple requires two-factor authentication, and automated machines cannot answer a two-factor prompt.
Common symptoms include Fastlane hanging on a verification code prompt, errors about invalid credentials, or a previously working session suddenly expiring. On CI these failures are especially disruptive because no human is present to approve the login.
The durable fix is to stop using Apple ID and password authentication for automation and switch to an App Store Connect API key.
That single change removes the entire class of interactive login problems, rather than patching each symptom individually.
It helps to think of Apple ID authentication as a human logging in and API-key authentication as a machine presenting a token. Automation wants the second model, and most authentication pain comes from trying to force the first model into an unattended pipeline.
Fastlane supports two broad authentication approaches. The older method uses your Apple ID and password, which Fastlane's underlying Spaceship layer uses to emulate a login. This path is subject to two-factor authentication and session expiry.
The modern method uses an App Store Connect API key, a token-based credential you generate in App Store Connect. API keys are not tied to interactive two-factor prompts and are designed for automation.
For anything unattended, the API key method is the correct choice.
The Apple ID method should be reserved, if used at all, for occasional interactive local runs where a human can answer prompts.
Knowing which method a given action uses is half the battle. Once you can look at a lane and identify every place it authenticates, migrating those spots to the API key becomes a straightforward, mechanical task.
In App Store Connect, go to Users and Access and find the section for integrations or keys. There you can generate an API key with an appropriate role. Note that only account holders or admins can typically create these keys.
When you generate the key, you receive a key ID, an issuer ID, and a downloadable private key file. The private key file can only be downloaded once, so store it securely immediately.
Guard these values like passwords.
Anyone with the key can act against your App Store Connect account within the permissions you granted it, so treat the key file as a sensitive secret from the moment you download it.
Fastlane's app_store_connect_api_key action loads the key and makes it available to subsequent actions like upload_to_testflight and deliver. You supply the key ID, issuer ID, and the key contents or file path.
On CI, pass these values through encrypted environment variables rather than committing the key file to your repository. Reconstruct or reference the key at runtime from those secrets.
Once the key is loaded, upload and metadata actions authenticate with it automatically, and the two-factor prompt disappears entirely.
Loading the key early in the lane ensures every later action inherits the authenticated context.
A practical pattern is to call the key-loading action as the very first step of any lane that touches App Store Connect. That way you never have to reason about whether a given action will find valid credentials; they are always in scope.
If your CI job is still hanging on a two-factor prompt, it means some action is still using Apple ID authentication instead of the API key. Audit your lane for any action that logs in with an Apple ID.
Ensure the API key is loaded early in the lane and that actions requiring App Store Connect access pick it up. When the API key is correctly in scope, there is no interactive login step to hang on.
For the parts of the Apple Developer portal that historically required Apple ID login, confirm your Fastlane version supports API-key authentication for those operations, and update if needed.
An out-of-date Fastlane is a common reason an otherwise correct API-key setup still falls back to interactive login.
Teams that still rely on Apple ID authentication sometimes cache a session to survive two-factor, but these sessions expire, causing intermittent failures that are maddening to debug.
Rather than chasing session renewal, migrate the affected operation to the API key. Session-based workarounds are inherently time-limited, whereas an API key does not require periodic interactive re-authentication.
If you must keep a session-based flow temporarily, understand it will break again when the session lapses.
Treat it as a stopgap, not a solution. Every hour spent extending a session is better spent migrating that operation to the API key.
Sometimes authentication succeeds but the operation fails with a permissions error. This means the API key's role lacks the rights for that action, such as submitting an app or editing certain metadata.
Check the role assigned to your API key in App Store Connect and grant the level appropriate for what your automation does. Follow least privilege: give the key only the access it needs.
If different lanes need different capabilities, you can create separate keys with different roles, which also limits exposure if one key is compromised.
Separate keys per purpose make it easier to revoke one without disrupting every pipeline at once.
Standardize on the App Store Connect API key across all automation: TestFlight uploads, metadata delivery, and signing operations where supported. Store the key ID, issuer ID, and private key as encrypted secrets in your CI system.
Rotate keys periodically and revoke any key that may have leaked. Because revoking a key immediately disables it, keep track of which pipelines depend on which key.
With API-key authentication in place, the entire class of two-factor and session-expiry failures disappears, and your automation runs unattended as intended.
Document which key each pipeline uses so a future rotation does not silently break a release lane.
With this foundation in place, authentication becomes a solved problem rather than a recurring emergency. New pipelines simply reference the appropriate encrypted secrets, and your releases run unattended the way automation is meant to.
Switch from Apple ID and password authentication to an App Store Connect API key. API keys are token-based and not subject to interactive two-factor prompts, which is what unattended automation needs.
In App Store Connect under Users and Access, in the keys or integrations section. You receive a key ID, an issuer ID, and a private key file that can be downloaded only once.
Session-based workarounds for Apple ID two-factor authentication are time-limited by design. Migrating the operation to an App Store Connect API key removes the expiry problem entirely.
The API key's assigned role likely lacks the rights for that operation. Adjust the key's role in App Store Connect to grant the necessary access, following least privilege.