Authenticating with Apple services

Several fastlane actions communicate with Apple services that need authentication. As this can pose several challenges especially on CI, this document focuses on those challenges, but everything described here can be done on your local machine as well.

There are 4 ways to connect to Apple services:

This is the recommended and official way of authenticating with Apple services. However, it doesn't support all of the fastlane features yet. Check out App Store Connect API for more information.

Method 2: Two-step or two-factor authentication

For actions that aren't yet supported by the official App Store Connect API, you will need to authenticate with your Apple ID. Luckily, fastlane fully supports 2-factor authentication (2FA) (and legacy 2-step verification (2SV)) for logging in to your Apple ID and Apple Developer account. 🌟

Manual verification

With 2-factor authentication (or 2-step verification) enabled, you will be asked to verify your identity by entering a security code. If you already have a trusted device configured for your account, then the code will appear on the device. If you don't have any devices configured, but have trusted a phone number, then the code will be sent to your phone.

The resulting session will be stored in ~/.fastlane/spaceship/[email]/cookie.

Storing a manually verified session using spaceauth

As your CI machine will not be able to prompt you for your two-factor authentication or two-step verification information, you can generate a login session for your Apple ID in advance by running:

fastlane spaceauth -u user@email.com

The generated value then has to be stored inside the FASTLANE_SESSION environment variable on your CI system. This session will be reused instead of triggering a new login each time fastlane communicates with Apple's APIs.

It's advised that you run spaceauth in the same machine as your CI, instead of running it locally on your machine - see the notes below regarding session duration.

Important note about session duration

The session generated, stored and reused as part of a 2FA/2SV authentication, or as part of spaceauth is subject to technical limitations imposed by Apple. Namely:

  • An Apple ID session is only valid within a certain region, meaning if the region you're using your session (e.g. CI system) is different than the region where you created that session (e.g. your local machine), you might run into issues. It's advised that you create the session in the same machine that will be used to consume it, to make the session last longer.
  • The session's validity can greatly vary (anything between 1 day and 1 month, depending on factors such as geolocation of the session usage). This means you'll have to generate a new session at least once a month. Usually you'd only know about it when your build starts failing.

Unfortunately there is nothing fastlane can do better in this regard, as these are technical limitations on how App Store Connect sessions are handled.

Method 3: Application-specific passwords

If you want to upload builds to App Store Connect (actions upload_to_app_store and deliver) or TestFlight (actions upload_to_testflight, pilot or testflight) from your CI machine, you may generate an application specific password:

  1. Visit appleid.apple.com/account/manage
  2. Generate a new application specific password
  3. Provide the application specific password using the environment variable FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD

This will supply the application specific password to iTMSTransporter, the tool used by those actions to perform the upload.

Note: The application specific password will not work if your action usage does anything else than uploading the binary, e.g. updating any metadata like setting release notes or distributing to testers, etc. For those actions, you must use one of the other methods.

Method 4: Apple ID without 2FA (deprecated)

Apple announced that as of February 27th 2019, it would enforce 2-factor authentication on developer Apple IDs with the "Account Holder" role. Since then, they extended this rule to all roles, and then later throughout 2020 they slowly enforced all existing accounts to register 2FA. As of March 3rd 2021, no accounts without 2FA registered are able to login until they register a 2FA method, essentially breaking all "non-2FA compliant Apple IDs" that still existed. For this reason, when using fastlane in your CI, you will have to work your way with 2FA.